OpenSEO is an open source SEO tool for individuals and teams, positioned as a lightweight alternative to commercial suites such as Semrush and Ahrefs. It provides keyword research, ranking tracking, competitive product analysis, backlinks, site auditing and AI Visibility, and hands over SEO data to AI Agents such as Codex and Claude Code through MCP for use.
OpenSEO can use the official hosted version, or you can deploy it yourself. Self-hosting gives you control over application and project data, but does not mean that all SEO data is free: data such as keywords, SERPs, backlinks, etc. comes from DataForSEO, which still requires its own API credentials and pays per call.
Quick Answer
To experience OpenSEO on a personal computer, it is recommended to use Docker:
|
|
Set in .env:
|
|
Start the service:
|
|
The default access address is:
|
|
Important reminder: Docker self-hosted mode uses AUTH_MODE=local_noauth by default and has no application-level login checks. It is suitable for local machines or trusted private networks and cannot directly expose ports to the public network. Remote access must be behind an authenticated reverse proxy, tunnel, or private network.
What OpenSEO can do
OpenSEO breaks down common SEO work into more focused processes:
| Workflow | Solved problems |
|---|---|
| Keyword Research | Query search volume, difficulty, CPC, intent and trends |
| Rank Tracking | Save keywords and track the latest rankings |
| Competitor Insights | Find competing organic keywords, pages and traffic leads |
| Backlinks | View an overview of backlinks and referring domains |
| Site Audits | Check site technical issues and page status |
| AI Visibility | Observe the visibility of a brand or page in AI search scenarios |
MCP can also read Google Search Console clicks, impressions, CTR and average position, and check the indexing, crawling and canonical status of a given URL. Which data can actually be called depends on the current version, the connected data source, and account permissions.
Understand the costs before self-hosting
OpenSEO itself uses the MIT License, but it relies on a third-party DataForSEO to obtain SEO data. When self-hosted, the call fee is paid directly by the user to DataForSEO.
The official documentation states that new DataForSEO accounts can obtain a small amount of test quota and have a minimum recharge amount; these price policies may change, and you should check the current DataForSEO billing page before registering. Don’t commit production API credentials to Git, and don’t paste the full Base64 string into logs, tickets, or chat logs.
The credentials provided by DataForSEO are the Base64 values that combine the account email and API password. The format source is:
|
|
Base64 is only encoding, not encryption. Someone who gets their hands on DATAFORSEO_API_KEY may drain account balances or access permitted data, so it should be managed like a password.
Self-hosting using Docker
1. Clone project
|
|
2. Create environment variable file
|
|
Edit .env to include at least the DataForSEO credentials:
|
|
Optional configurations include:
|
|
PORT Default is 3001. ALLOWED_HOST is used to allow a reverse proxy hostname. If you do not want to send anonymous telemetry, you can set OPENSEO_TELEMETRY_DISABLED=1, or you can use DO_NOT_TRACK=1.
3. Start and check
|
|
Confirm the configuration actually read by Compose:
|
|
The output here may contain sensitive environment variables and should not be copied directly to public issues or CI logs. After the check is complete, open http://localhost:3001.
4. Rebuild the container after modifying the configuration
Modify .env and run:
|
|
Just performing a normal restart will not necessarily reapply all environment variables, and forcing a rebuild makes it easier to eliminate the remnants of old configurations.
Why can’t Docker mode directly expose the public network?
The official Compose uses AUTH_MODE=local_noauth, the local administrator is admin@localhost, and normal authentication will not be performed. If you map the 3001 port directly to the public network, anyone with access to the address could potentially enter the application and use the configured DataForSEO credentials.
A secure remote access solution should satisfy at least one of the following:
- Only allow access through private networks such as WireGuard and Tailscale;
- Place behind a reverse proxy with strong authentication;
- Use secure tunnels with authentication and access policies;
- Switch to the official Cloudflare self-hosted solution.
When configuring the reverse proxy domain name, set it in .env:
|
|
Then rebuild the service:
|
|
Simply configuring ALLOWED_HOST does not replace authentication, it is only part of the hostname restriction.
Updates, Fixed Versions and Rollbacks
Pull the latest image and restart:
|
|
It is not recommended to use floating latest for a long time in a production environment. Verified image tags can be pinned in .env:
|
|
The example tag is only used to show the configuration format. You should actually select an existing and verified version from the official Releases. Back up persistent data and record old tags before updating; restore old images and compatible data versions when problems occur.
Stop the container:
|
|
The following command will delete the volume together. Do not execute it without backup:
|
|
Turn off anonymous telemetry
Official documentation states that OpenSEO will send core usage events and aggregate counts with random installation IDs. The documentation states that URLs, keywords, prompts, email addresses, or IP-based inferred locations are not collected, and idle instances do not send data.
To turn it off, set it in .env:
|
|
Then rebuild the container:
|
|
For environments with strict compliance requirements, you should still check the current version of the code, network exits, and privacy statements yourself, rather than relying solely on summary descriptions.
Self-hosted using Cloudflare
When you need access from the public network across devices or teams, OpenSEO also provides a Cloudflare deployment path using the Cloudflare free plan. The official process is roughly as follows:
- Create a Worker through the Deploy to Cloudflare portal provided by the warehouse;
- Connect to GitHub or GitLab;
- Enable Cloudflare Access in Worker Domains & Routes;
- Add authentication and DataForSEO configuration in Variables & Secrets;
- Open the Worker URL and verify login with the OpenSEO page.
Secrets that need to be configured include:
|
|
POLICY_AUD and TEAM_DOMAIN come from Cloudflare Access settings. Do not write them to the repository’s normal variable files.
DataForSEO responses are cached in R2 under the dataforseo-cache/ prefix. The official recommendation is to set life cycle rules to automatically clear expired caches:
|
|
If the R2 Bucket name is changed during deployment, you need to replace open-seo in the command with the actual name. When lifecycle rules are not configured, cached objects continue to accumulate and increase storage costs.
Connect OpenSEO MCP to Claude Code
The official hosting MCP address is:
|
|
Add user-level MCP in Claude Code:
|
|
The first time you connect will enter the OpenSEO login and authorization process. If you only want to use the current repository, you can use the local scope according to the current version of Claude Code.
Connect OpenSEO MCP to Codex
Codex CLI uses:
|
|
Then follow the prompts to complete the login authorization. Codex Desktop users can go to Settings, Integrations & MCP, select Add Custom Service, and then paste the same URL.
After the connection is successful, first let the Agent list the OpenSEO projects and obtain the project ID, and then perform keyword research or ranking analysis. Instead of just saying “do my SEO for me” at first, a more effective request would include the website, market, language, goals, and output scope.
For example:
|
|
The difference between MCP and Agent Skills
MCP provides Agent with the tools to query and write OpenSEO data; Agent Skills specifies how to combine these tools to complete a job. The former solves “what can be accessed”, and the latter solves “what process should be followed”.
Officially listed MCP capabilities include:
- Query keyword search volume, difficulty, CPC and intent;
- Get real-time Google organic search results;
- Analyze the ranking keywords of domain names or pages;
- Compare SERP competitors across keyword sets;
- Query backlinks and referring domain profiles;
- Read Search Console performance and URL index status.
When authorizing AI Agent, account and project scope should be limited. Verify that the selected item is correct with a read-only query before asking the Agent to write saved keywords or change item data.
FAQ
The page can be opened, but querying SEO data fails.
First check whether DATAFORSEO_API_KEY is the complete Base64 credential provided by DataForSEO and whether the account has a balance, and then use the following command to confirm that Compose has read the environment variable:
|
|
Don’t expose credentials in troubleshooting screenshots. Force the rebuild of the open-seo container after modifying .env.
After reverse proxy, it prompts that the host is not allowed.
Set ALLOWED_HOST in .env to the actual public hostname, without including the path, and rebuild the container. At the same time, authentication must be configured at the proxy layer.
MCP cannot connect
Confirm that the address is exactly:
|
|
When authorization fails, first remove OpenSEO MCP from the client, then add it again and complete the login. When the Agent cannot find an item, it first calls the item list and uses the returned item ID in subsequent requests.
Is self-hosting completely free?
The app code runs on its own, but the SEO data is provided by DataForSEO, for which you pay a price. There may also be additional costs for Cloudflare, servers, domain names, backups, and networking.
Who is OpenSEO suitable for?
OpenSEO is suitable for individual webmasters and small teams who want to purchase SEO data by usage, need centralized workflows such as keywords and rankings, or want AI Agent to directly use SEO data. Docker mode is suitable for local experience, and Cloudflare plan is more suitable for multi-device and team access.
If you need a large historical database, mature enterprise permissions, complete auditing, and a large number of out-of-the-box reports, you should first compare the data coverage, update frequency, and total cost of OpenSEO with commercial platforms using real projects, and don’t just migrate based on the positioning of “open source alternative”.
Summary
OpenSEO puts keyword research, rankings, competitive products, links, site audits and Search Console data into an open source interface, and makes it available to agents such as Codex and Claude through MCP. Personal experience can start with Docker, but you must remember that local mode does not have application authentication; team or public network deployment should use Cloudflare Access or a self-built strong authentication boundary. While self-hosting allows you to control the application and process, DataForSEO call costs remain separate.
Project address: every-app/open-seo
Official documentation: openseo.so/docs