Core Features of Open-SEO: Complete Technical Guide to the Open-Source SEO Platform

Open-SEO provides six production-grade SEO workflows—keyword research, rank tracking, competitor insights, backlink analysis, site audits, and AI visibility—packaged as a type-safe, self-hostable TypeScript application with native MCP server support for AI agent automation.

Open-SEO (available at every-app/open-seo) delivers the core features of open-seo tooling as a transparent, hackable alternative to proprietary platforms like Semrush and Ahrefs. Built on a TanStack server-function architecture with Zod-validated TypeScript contracts, the platform enables teams to own their data while integrating DataForSEO APIs for live search intelligence.

Primary SEO Workflows

Keyword Research with DataForSEO Integration

The keyword research module connects to the DataForSEO API to generate keyword ideas, search volume, CPC estimates, and keyword difficulty scores. Frontend components consume this data through the useKeywordResearchData hook located in src/client/features/keywords/hooks/useKeywordResearchData.ts, which performs a strongly-typed fetch to the REST endpoint GET /api/v1/projects/:projectId/keyword-research.

// Example: Fetch keyword research data from the API
const response = await fetch(
  `/api/v1/projects/${PROJECT_ID}/keyword-research?keyword=coffee&location=us`
);
const data = await response.json();

The Zod schemas in src/shared/rank-tracking.ts enforce runtime type safety for all API responses, ensuring that malformed data from external providers never propagates to the UI.

Automated Rank Tracking

Rank tracking functionality stores historical SERP positions for target keywords and schedules periodic position checks via DataForSEO’s task queue. The business logic resides in src/shared/rank-tracking.ts, which exports request builders and validation schemas used by both the frontend polling mechanisms and background job processors.

Server-side implementation in src/serverFunctions/rank-tracking.ts handles the orchestration of tracking jobs, storing results in the database-agnostic Drizzle ORM layer configured in drizzle.config.ts.

Competitor Insights via Ahrefs-Style API

The competitor analysis feature aggregates organic traffic estimates, top-performing keywords, and domain authority metrics. Implementation in src/serverFunctions/ahrefs.ts adapts DataForSEO responses to match familiar Ahrefs-style data structures, making migration from commercial tools straightforward.

Backlink Profile Analysis

Backlink data collection—including anchor text distribution, referring domain authority, and link-type categorization—is managed by src/serverFunctions/backlinks.ts. This module exposes endpoints consumed at /api/v1/projects/:projectId/backlinks, providing granular visibility into off-page SEO factors.

Technical Site Audits

Site audit functionality combines crawlability analysis with Lighthouse performance data. The coordinator in src/serverFunctions/audit.ts aggregates technical SEO checks (indexability, mobile usability, page speed) by leveraging src/shared/lighthouse.ts for Core Web Vitals and rendering metrics.

// Example: Trigger a site audit from the client UI
import { useQuery } from '@tanstack/react-query';

function AuditTrigger({ projectId }: { projectId: string }) {
  const { refetch } = useQuery(
    ['siteAudit', projectId],
    () => fetch(`/api/v1/projects/${projectId}/audit`).then(r => r.json())
  );
  
  return <button onClick={() => refetch()}>Run Technical Audit</button>;
}

AI Visibility and Insights

The AI visibility module uses OpenAI-compatible prompts to transform raw SEO metrics into strategic recommendations. Logic in src/serverFunctions/ai-search.ts and src/shared/keyword-locations.ts processes ranking data to generate automated insights about content opportunities and competitive positioning.

MCP Server and AI Agent Integration

Open-SEO exposes its data model through an MCP (Model Context Protocol) server 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 without manual UI interaction.

// Example: Trigger rank tracking via the MCP server
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 MCP handler routes actions like trackRank to the appropriate service layers, enabling fully automated SEO monitoring pipelines.

Self-Hosting and Deployment Architecture

Open-SEO supports two primary self-hosting strategies that accommodate both personal users and enterprise deployments:

• Docker (Simple): Run a single container locally for immediate access to all core features of open-seo without external dependencies beyond a DataForSEO API key.
• Cloudflare Workers (Advanced): Deploy globally distributed edge functions for production-scale availability, utilizing the same serverless-friendly architecture found in src/server.ts.

Both configurations require a user-provided DataForSEO API key, which the application references at runtime—credentials are never hardcoded in the repository source.

Database and Infrastructure

The application maintains database flexibility through Drizzle ORM, supporting both SQLite for local development and PostgreSQL for production workloads. Configuration in drizzle.config.ts handles schema migrations across both providers, while Zod schemas in src/types/*.ts enforce strict input validation at API boundaries.

Summary

• Open-SEO delivers six integrated SEO workflows: keyword research, rank tracking, competitor insights, backlink analysis, site audits, and AI visibility.
• The architecture relies on TanStack server-functions with Zod validation, ensuring type safety from API to UI.
• Native MCP server support in src/server.ts enables direct AI agent integration for automated SEO tasks.
• Flexible deployment options include Docker containerization and Cloudflare Workers edge deployment.
• All integrations require only a DataForSEO API key, keeping hosting costs limited to infrastructure and third-party data usage.

Frequently Asked Questions

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

Open-SEO provides the same foundational capabilities—keyword research, rank tracking, and site audits—through an open-source codebase that allows complete data ownership and custom integration. Unlike proprietary platforms, you host the infrastructure, control API rate limits, and extend functionality by modifying src/serverFunctions files directly.

How does the MCP server enable AI automation in Open-SEO?

The MCP server exposes SEO operations as programmatic endpoints, allowing AI agents to query ranking data, trigger audits, and receive structured JSON responses. This architecture, implemented in src/server.ts, transforms Open-SEO from a manual dashboard into an autonomous SEO agent that can monitor competitors and track keyword movements without human intervention.

Can I self-host Open-SEO without using DataForSEO?

Currently, the core features of open-seo—including keyword volume, SERP positions, and backlink data—depend on DataForSEO as the underlying data provider. While the UI and processing logic remain fully open-source and self-hosted, retrieving live search data requires a DataForSEO API key, as implemented in src/serverFunctions/ahrefs.ts and related service files.

What database options does Open-SEO support?

The platform uses Drizzle ORM configured in drizzle.config.ts to support both SQLite for local development and PostgreSQL for production environments. This abstraction allows the same rank-tracking and audit schemas to function across different database backends without code changes.

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