Read the whole setupGet the setup that works.
Drop your email and unlock the rest: what you need, the Cloudflare self-host path, the DataForSEO key setup, and the MCP connection for Claude Code.
One email. No follow-up unless I ship something that fits.
WHAT YOU NEED- A DataForSEO account and API key, billed separately by them
- A Cloudflare account on the free plan, for the recommended self-host path
- Docker, only if you are testing locally instead of deploying to Cloudflare
INSTALLCloudflare for anything internet-facing
Docker is the fastest way to try it on your own machine. Cloudflare is the path worth setting up if more than one person, or more than one device, will use it.
The install
terminalcloned repo
$ git clone https://github.com/every-app/open-seo.git $ cp .env.selfhost.example .env.selfhost $ pnpm deploy:selfhost → deployed via alchemy to your Cloudflare account
The Docker path uses compose.yaml and Dockerfile.selfhost directly for a local-only instance, no Cloudflare account required.
Prove itRun one keyword-research query after setup. A real result with volume and difficulty numbers confirms the DataForSEO key is wired correctly.
CONFIGUREThe key and the auth mode
.env.selfhost is where the DataForSEO key and auth mode live. Auth mode decides who can reach the instance once it is deployed.
.env.selfhostmy values
DATAFORSEO_API_KEY= AUTH_MODE=cloudflare_access TEAM_DOMAIN=https://your-team.cloudflareaccess.com
| Setting | Default | Why I change it |
|---|
| AUTH_MODE | cloudflare_access | Right for a team deploy behind Cloudflare Access. Switch to local_noauth only for a single-user local instance you fully trust. |
| DATAFORSEO_API_KEY | unset | Required before any SEO data loads. Get one from DataForSEO directly, not through OpenSEO. |
Local testinglocal_noauth mode injects a trusted admin user automatically, fine for a laptop-only instance, wrong for anything reachable from outside your machine.
DAILY DRIVINGDashboard for you, MCP for the agent
Use the dashboard for a workflow you are doing yourself. Use MCP when you want Claude Code to pull the same data into a task without you copying numbers over.
- Set up MCP once. Point Claude Code at your OpenSEO instance's MCP endpoint following openseo.so/docs/mcp, then agent skills can call it directly.
- Run audits from the agent. "Audit this URL for broken backlinks" reaches DataForSEO through your own instance, billed to your own key.
- Track rank changes over time. Rank tracking runs on the schedule you set, not a fixed daily crawl you cannot adjust.
The MCP path is what makes this worth self-hosting over a free-tier SaaS tool: the data stays queryable by an agent, not locked in someone else's dashboard.
WHEN IT DRIFTSTwo failures, both configuration
No SEO data loads at all
DATAFORSEO_API_KEY is unset or invalid. Check docs/DATAFORSEO_API_KEY.md for how to generate and verify one.
Team members cannot reach the instance
AUTH_MODE is still local_noauth on a Cloudflare deploy. Switch to cloudflare_access and set TEAM_DOMAIN and POLICY_AUD.
Cost checkSelf-hosted costs track DataForSEO's own pricing directly, with no markup. If a bill looks high, the query volume is the thing to look at, not OpenSEO itself.
THE SHAPE OF ITWhere everything lives
.env.selfhostyour DataForSEO key and auth settings docs/SELF_HOSTING_CLOUDFLARE.mdthe recommended deploy path, step by step docs/SELF_HOSTING_DOCKER.mdthe local-only path .claude/skills/the pre-built agent skills for common SEO workflows drizzle/the database schema, SQLite or Postgres compatible
Everything your instance stores lives in your own database, either the SQLite default or a Postgres you point it at.
That is the whole setupOne DataForSEO key, one Cloudflare deploy, and the seat-based SEO subscription is gone. The MCP server is what turns it from a dashboard replacement into something your agent can use directly.
Open on GitHub →
↑ Unlocks the moment you submit the form above.
