OpenSEO Features: Complete Guide to the Open-Source SEO Toolkit

OpenSEO delivers enterprise-grade SEO capabilities—including keyword research, rank tracking, competitor analysis, backlink monitoring, site audits, and AI visibility—through a type-safe, modular TypeScript architecture that supports both REST APIs and MCP server integration.

OpenSEO is a modern open-source SEO platform maintained by the every-app organization that provides the core functionality of commercial tools like Semrush and Ahrefs while remaining fully self-hostable. The codebase emphasizes strict TypeScript typing with Zod validation, a clean separation between server functions and client hooks, and native support for AI agents via the Message Control Protocol (MCP).

Core SEO Workflows

OpenSEO organizes its functionality around six primary SEO workflows defined in the project README (lines 28-35). Each workflow maps to specific server-side implementations in src/serverFunctions/ and corresponding client-side data fetching hooks.

Keyword Research

The keyword research module generates search volume, CPC, and keyword difficulty data by integrating with the DataForSEO API. Client components consume this data through the useKeywordResearchData hook located in src/client/features/keywords/hooks/useKeywordResearchData.ts, which performs a GET request to /api/v1/projects/${projectId}/keyword-research. The endpoint uses Zod schemas defined in src/types/ to validate incoming query parameters and outgoing response shapes.

Rank Tracking

Rank tracking functionality schedules periodic SERP position checks for monitored keywords and maintains historical ranking data. The business logic resides in src/shared/rank-tracking.ts, which exports Zod schemas for request validation and provides utilities for building DataForSEO task queues. The server-side endpoint handling these operations is implemented in the serverFunctions layer, queuing tasks to DataForSEO's API and persisting results via Drizzle ORM.

Competitor Insights

OpenSEO retrieves competitor domain metrics, organic traffic estimates, and top-performing keywords through the competitor insights feature. This implementation adapts Ahrefs-style API responses to OpenSEO's internal data model in src/serverFunctions/ahrefs.ts, allowing users to analyze rival domains without third-party subscription lock-in.

Backlinks

The backlinks module collects comprehensive link profiles, including anchor text distribution, referring domain authority, and link-type categorization (follow vs. nofollow). Server-side logic in src/serverFunctions/backlinks.ts exposes endpoints consumed by the UI at /api/v1/projects/:projectId/backlinks, enabling real-time analysis of site authority metrics.

Site Audits

Technical SEO audits run via the site audits feature, which aggregates crawlability metrics, indexability status, and Lighthouse performance data. The coordinator logic lives in src/serverFunctions/audit.ts, while performance-specific utilities are wrapped in src/shared/lighthouse.ts. These components generate comprehensive reports covering page speed, mobile usability, and structured data validation.

AI Visibility

The AI visibility workflow uses OpenAI-compatible prompts to transform raw SEO metrics into strategic recommendations. Server-side pipelines in src/serverFunctions/ai-search.ts and location-aware keyword processing in src/shared/keyword-locations.ts enable AI agents to interpret ranking fluctuations and suggest content optimizations.

MCP Server and Agent Integration

OpenSEO distinguishes itself from traditional SEO tools by exposing all functionality through an MCP server (Message Control Protocol) defined in src/server.ts. This JSON-RPC-style interface allows AI agents such as Claude Code or custom automation scripts to invoke SEO workflows directly.

Agents can trigger rank tracking scans, fetch keyword data, or initiate site audits without interacting with the React frontend. The MCP handler routes incoming actions to the appropriate service layer—for example, mapping a trackRank action to the rank-tracking service in src/shared/rank-tracking.ts.

Technical Architecture

OpenSEO follows a TanStack server-function → service → repository pattern that ensures type safety from database to client.

Type-Safe Data Layer

All external inputs are validated using Zod schemas, preventing runtime errors from malformed DataForSEO responses. The database layer uses Drizzle ORM (configured in drizzle.config.ts) and supports both SQLite for local development and PostgreSQL for production deployments.

Modular Server Functions

Each major feature is isolated in its own src/serverFunctions/ file—such as gsc.ts for Google Search Console integration, domain.ts for domain management, and billing.ts for subscription handling. This modularity keeps the HTTP layer thin and allows individual functions to be tested or deployed independently.

Self-Hosting Deployment Options

OpenSEO supports two primary self-hosting strategies that give users full data sovereignty.

• Docker deployment provides a single-container setup optimized for local development or small teams. Configuration files and setup instructions are documented in docs/SELF_HOSTING_DOCKER.md.

• Cloudflare Workers deployment offers a globally distributed, edge-computed architecture suitable for high-traffic scenarios. Advanced configuration details reside in docs/SELF_HOSTING_CLOUDFLARE.md.

Both approaches require a DataForSEO API key, which users provide via environment variables—the key is never hardcoded in the repository source.

Practical Code Examples

The following examples demonstrate how to interact with OpenSEO's API endpoints and MCP interface using TypeScript.

Fetching Keyword Research Data

To retrieve keyword suggestions programmatically, call the REST endpoint used by the internal React hooks:

// Replace PROJECT_ID with your actual project UUID
const response = await fetch(
  `/api/v1/projects/${PROJECT_ID}/keyword-research?keyword=coffee&location=us`
);
const data = await response.json();
console.log('Keyword volume and difficulty:', data);

This endpoint leverages the useKeywordResearchData hook pattern and validates responses against Zod schemas in src/types/schemas/keywords.ts.

Triggering Rank Tracking via MCP

AI agents can queue rank tracking tasks by posting to the MCP endpoint:

await fetch('https://your-openseo-instance.com/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'trackRank',
    projectId: 'PROJECT_ID',
    keywords: ['coffee', 'espresso'],
    location: 'us',
    devices: ['desktop', 'mobile']
  })
});

The request is routed through src/server.ts to the rank-tracking implementation in src/shared/rank-tracking.ts, which schedules tasks with DataForSEO.

Running Site Audits from the Client

Client components can trigger technical audits using TanStack Query:

import { useQuery } from '@tanstack/react-query';

function AuditButton({ projectId }: { projectId: string }) {
  const { data, refetch } = useQuery(
    ['siteAudit', projectId],
    () => fetch(`/api/v1/projects/${projectId}/audit`).then(r => r.json())
  );

  return <button onClick={() => refetch()}>Run Technical Audit</button>;
}

This invokes the audit coordinator in src/serverFunctions/audit.ts, which aggregates Lighthouse performance data and backlink metrics into a unified report.

Summary

• OpenSEO provides six core SEO workflows: keyword research, rank tracking, competitor insights, backlinks, site audits, and AI visibility.
• The architecture uses TypeScript with Zod validation and Drizzle ORM, supporting both SQLite and PostgreSQL backends.
• A built-in MCP server in src/server.ts enables AI agents to automate SEO tasks via JSON-RPC calls.
• Self-hosting options include Docker for simplicity and Cloudflare Workers for distributed edge deployment.
• Code is organized into modular server functions (src/serverFunctions/ahrefs.ts, audit.ts, backlinks.ts, etc.) that maintain strict separation between API endpoints and business logic.

Frequently Asked Questions

What APIs does OpenSEO use for SEO data?

OpenSEO integrates primarily with the DataForSEO API to retrieve keyword volumes, SERP rankings, and backlink profiles. Users must provide their own DataForSEO API key via environment variables, as the open-source codebase does not include proprietary data sources.

Can I self-host OpenSEO without using Docker?

Yes. While Docker provides the simplest path for local deployment, OpenSEO also supports Cloudflare Workers for serverless edge deployment. Documentation for the Cloudflare approach is available in docs/SELF_HOSTING_CLOUDFLARE.md, offering a scalable alternative for production environments.

How does the MCP server enable AI automation?

The MCP server exposed in src/server.ts implements a JSON-RPC interface that translates agent commands into SEO workflow executions. AI agents can invoke actions like trackRank or fetch keyword research data without browser automation, directly accessing the business logic in src/shared/rank-tracking.ts and related modules.

Is OpenSEO suitable for large-scale agency use?

Yes. The modular server-function → service → repository architecture allows horizontal scaling, particularly when deployed on Cloudflare's edge network. The Drizzle ORM configuration supports PostgreSQL for high-concurrency scenarios, and the type-safe Zod schemas prevent data corruption across distributed teams.

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