What Is the OpenSEO Project? Purpose, Architecture, and Self-Hosting Guide

OpenSEO is an open-source, self-hostable SEO platform that delivers a pay-as-you-go alternative to commercial tools like Semrush and Ahrefs, exposing SEO workflows through a Modular Control Plane (MCP) server that AI agents interact with via reusable Agent Skills.

The every-app/open-seo repository provides a transparent backend engineered to eliminate expensive subscriptions while maintaining enterprise-grade SEO functionality. Unlike proprietary SaaS solutions, OpenSEO grants full control over data and costs by integrating directly with the DataForSEO API and supporting flexible deployment options. Its core purpose centers on democratizing professional SEO tooling through modular architecture and AI-agent compatibility.

How OpenSEO Fulfills Its Core Purpose

The Modular Control Plane (MCP) Server

At the heart of OpenSEO lies the Modular Control Plane (MCP) server, which exposes a lightweight HTTP API that AI agents—such as Claude Code, OpenClaw, and Hermes—can invoke to retrieve SEO data and trigger workflows. This architecture transforms traditional SEO tasks into programmatic operations suitable for autonomous execution. According to README.md (lines 37-40), "OpenSEO exposes an MCP server so AI agents… can use your SEO data directly."

Agent Skills for Automated Workflows

Agent Skills are pre-built, reusable YAML definitions encoding step-by-step logic for tasks including keyword research, site audits, and competitor analysis. These skills guide AI agents through complex workflows using the MCP interface. The source code loads these definitions automatically from the skills/ directory, where custom YAML files can be added to extend functionality.

Transparent Data Pricing via DataForSEO

Rather than marking up data costs, OpenSEO integrates with the DataForSEO API, requiring users to supply their own API key for raw search-engine data. As documented in docs/DATAFORSEO_API_KEY.md and README.md (lines 51-56), this approach ensures transparent pricing: "OpenSEO needs a DataForSEO API key… you pay them directly when self-hosting."

Self-Hosting Architecture and Deployment Paths

OpenSEO supports two distinct self-hosting paths tailored to different operational scales, as detailed in docs/SELF_HOSTING_DOCKER.md (lines 46-50).

Simple Docker Deployment

For personal use or small teams, the Simple Docker setup provides the fastest path to running OpenSEO locally. This configuration launches the MCP server on port 3001 with AUTH_MODE=local_noauth, eliminating authentication barriers for local development.

# Copy the example env file and set your DataForSEO key

cp .env.example .env

# Edit .env → set DATAFORSEO_API_KEY=<base64(email:password)>

# Launch the stack

docker compose up -d

When the container starts, the server listens on http://localhost:3001 and operates without auth checks, as specified in docs/SELF_HOSTING_DOCKER.md (lines 15-31).

Advanced Cloudflare Workers Deployment

For team-scale, internet-facing installations, OpenSEO offers an Advanced Cloudflare deployment path leveraging Cloudflare Workers for edge distribution. This configuration utilizes type definitions found in worker-configuration.d.ts to manage the Cloudflare environment, providing greater scalability and global availability compared to the Docker approach.

Key Source Files and Database Structure

Understanding OpenSEO's implementation requires examining several critical files that define its architecture:

File	Purpose
README.md	High-level overview, marketing content, and core architectural concepts
docs/SELF_HOSTING_DOCKER.md	Docker configuration, environment variables, and telemetry controls
docs/DATAFORSEO_API_KEY.md	Instructions for obtaining and formatting the required API credentials
worker-configuration.d.ts	TypeScript definitions for Cloudflare Workers environment
drizzle.config.ts & drizzle-pg/**	Database schema definitions using Drizzle ORM for persisting projects and crawl data
scripts/cli-utils.ts	CLI utilities powering the opencode command-line interface

The database layer utilizes Drizzle ORM with support for SQLite or Postgres, defined in drizzle.config.ts and the drizzle-pg/ directory, enabling persistent storage of keyword rankings, backlink profiles, and site audit results.

Controlling Privacy and Telemetry

OpenSEO collects only aggregated, anonymized usage events—including install ID and feature usage statistics—to guide product development. Users can disable this telemetry entirely by setting an environment variable before starting the container.

# Add to your .env file

OPENSEO_TELEMETRY_DISABLED=1

# Restart the container to apply changes

docker compose up -d --force-recreate open-seo

This configuration option is documented in docs/SELF_HOSTING_DOCKER.md (lines 42-47), ensuring users maintain full privacy control when self-hosting.

Extending OpenSEO with Custom Agent Skills

Because OpenSEO is fully open source, developers can fork the repository and create custom Agent Skills to extend functionality beyond the built-in keyword research, rank tracking, and backlink analysis tools. Custom skills follow a YAML structure placed in the skills/ directory.

name: custom-backlink-analysis
description: Retrieve backlink profile for a domain and rank it by authority
steps:
  - fetch: /api/backlinks?domain={{domain}}
  - transform:
      script: |
        // Sort backlinks by domain authority
        return data.sort((a, b) => b.authority - a.authority);
  - output: "{{result}}"

As noted in README.md (lines 26-27), the project encourages this extensibility: "Fork and vibe code your own custom tool."

Interacting with the MCP API Programmatically

AI agents communicate with OpenSEO through standard HTTP requests to MCP endpoints. The following TypeScript example demonstrates how an agent might trigger keyword research:

import axios from "axios";

const MCP_BASE = "http://localhost:3001/api";

async function getKeywordIdeas(projectId: string, seed: string) {
  const resp = await axios.post(`${MCP_BASE}/keyword-research`, {
    projectId,
    seed,
  });
  return resp.data; // → list of keyword suggestions
}

The MCP endpoints follow a JSON-over-HTTP contract documented via an automatically generated OpenAPI specification, allowing agents to discover available skills dynamically.

Summary

• OpenSEO serves as an open-source alternative to expensive SEO suites, offering pay-as-you-go pricing through direct DataForSEO API integration rather than marked-up subscriptions.
• The MCP server architecture enables AI agents to execute SEO workflows programmatically via reusable Agent Skills defined in YAML configuration files.
• Two deployment paths—Simple Docker for local development and Advanced Cloudflare for production-scale hosting—provide flexibility for individual developers and enterprise teams.
• Full source code transparency allows customization of skills and integration of additional data sources, while optional telemetry can be disabled via the OPENSEO_TELEMETRY_DISABLED=1 environment variable.
• Database persistence relies on Drizzle ORM with support for SQLite or Postgres, defined in drizzle.config.ts and the drizzle-pg/ schema files.

Frequently Asked Questions

What makes OpenSEO different from commercial SEO tools like Ahrefs or Semrush?

OpenSEO differs by providing a self-hostable, open-source backend that eliminates recurring subscription fees. While commercial tools charge marked-up prices for data access, OpenSEO connects directly to the DataForSEO API using your own credentials, ensuring you pay only for the data you consume. Additionally, the MCP server architecture allows AI agents to automate SEO tasks through programmable skills, an integration point unavailable in traditional SaaS SEO platforms.

Do I need programming skills to use OpenSEO?

Basic self-hosting requires only Docker and command-line familiarity to run the containerized version configured in docs/SELF_HOSTING_DOCKER.md. However, extending functionality through custom Agent Skills or modifying the MCP server logic requires TypeScript/JavaScript knowledge and understanding of the YAML skill definitions. The Simple Docker path provides a no-code entry point for consuming SEO data through existing skills.

How does the MCP server handle authentication in production?

The Simple Docker configuration runs with AUTH_MODE=local_noauth for local development, but production deployments—particularly the Advanced Cloudflare setup—implement proper authentication mechanisms. The worker-configuration.d.ts file defines the TypeScript interfaces for the Cloudflare environment, where you would configure authentication middleware appropriate for your team's security requirements.

Can I migrate my existing SEO projects from other platforms to OpenSEO?

OpenSEO stores project data, keywords, and crawl results in a Drizzle ORM-managed database (SQLite or Postgres), defined in drizzle.config.ts. While the repository does not provide automated importers for proprietary platforms, the open database schema in drizzle-pg/** allows developers to write migration scripts that import historical keyword rankings and backlink data into the OpenSEO structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}