OpenSEO is an open-source, self-hostable SEO platform — a pay-as-you-go alternative to Semrush and Ahrefs — covering keyword research, rank tracking, backlinks, site audits, Google Search Console, AI visibility, and Local SEO. It ships as both a web app and an MCP (Model Context Protocol) server, so AI agents like Claude Code, Codex, and Cursor can drive the same SEO workflows that human users see in the UI. The runtime is a Cloudflare Worker with Durable Objects, R2, and a dual database backend — D1 (SQLite) by default, Postgres via Hyperdrive as an opt-in for larger installs — with Docker as the alternative self-host path. Nearly all SEO data comes from DataForSEO, metered in credits; a managed hosted version runs at app.openseo.so alongside the self-hostable code in this repo.

Start with Orientation for the one-page picture of the project, then Version history if you want to know how it got here. The runtime and platform are covered by Agent workflows (which contains Worker entry and routing, the SAM chat agent and Onboarding chat agent Durable Objects, Rank tracking, and the Site audit pipeline), Auth modes and gating, Database and schema, and Costs, billing, and credits. Product surfaces live under SEO features (Rank tracking, Keyword research and saved keywords, DataForSEO client and metering) and MCP server (server entry, MCP transport and OAuth, Research and SERP tools, Search Console tools, Site audit tools, and Agent Skills and Cursor plugin). The Development and ops section groups Local development, Engineering conventions, Self-hosting, and Contributing and CI, with Playwright automation snippets at the top level as a reference for agent-driven browser tasks.

If you want to understand the architecture end-to-end, read Orientation, then Worker entry and routing, then Database and schema and Auth modes and gating. If you came to build or debug an MCP tool, start at MCP server, then MCP transport and OAuth, then the specific tool section (Research and SERP tools, Search Console tools, or Site audit tools). If you're adding a backend feature to the app, read Engineering conventions for the server-function → service → repository layering, then the closest existing feature under SEO features as a template. If you're self-hosting or setting up the repo locally, read Local development first, then Self-hosting for Docker or the Alchemy-based pnpm deploy:selfhost Cloudflare path, and Costs, billing, and credits to wire up DataForSEO.