deep-dive

Open-SEO Modules Explained: 10 Core Components and Their Purposes

August 2, 2026 every-app/open-seo ↗

Open-SEO modules are self-contained feature units that expose specific SEO capabilities through server-side workflows, MCP (Machine Control Protocol) tools, and helper services wired together via a TanStack-styled API layer.

The open-source every-app/open-seo repository is organized as a modular system where each business capability lives in its own folder with clean, reusable APIs. This architecture makes the codebase extensible for adding new SEO tools and portable for self-hosting on Docker or Cloudflare Workers. Below is a complete breakdown of every Open-SEO module, its purpose, and where to find the implementation.

Keyword Research Module

The Keyword Research module generates keyword ideas, search volumes, difficulty scores, CPC data, intent classification, and related terms. It powers the UI's "Keyword research" page and exposes functionality to AI agents via the research_keywords MCP tool.

Core implementation lives in src/server/mcp/tools/research-keywords.ts, which calls through to KeywordResearchService and ultimately the DataForSEO labs API.

import { researchKeywordsTool } from "@/server/mcp/tools/research-keywords";

async function example() {
  const result = await researchKeywordsTool.handler({
    projectId: "proj_123",
    mode: "related",          // "related" | "suggestions" | "ideas" …
    keyword: "open source seo",
    locale: "en",
  });

  console.log(result.structuredContent?.keywords?.slice(0, 5));
}

Rank Tracking Module

The Rank Tracking module periodically runs SERP lookups for keyword sets across selected devices, stores historical snapshots, and renders position graphs over time. This is implemented as two coordinated components:

import { getRankTrackerTool } from "@/server/mcp/tools/get-rank-tracker";

const resp = await getRankTrackerTool.handler({
  projectId: "proj_123",
  domain: "example.com",
  scheduleInterval: "daily",
});

console.log(resp.structuredContent?.keywords);

The RankTrackingService queries the rank_tracking table populated by the workflow.

The Backlinks module retrieves comprehensive backlink profiles, aggregates referring domains, and supports filtering and sorting of raw backlink rows. Two MCP tools provide layered access:

import { getBacklinksOverviewTool } from "@/server/mcp/tools/get-backlinks-overview";

const { structuredContent } = await getBacklinksOverviewTool.handler({
  domain: "example.com",
});

console.log(`Backlinks: ${structuredContent?.backlinks}`);

Both tools route through BacklinksService to the DataForSEO backlinks endpoint.

Site Audits Module

The Site Audits module crawls websites while respecting robots.txt, detects SEO issues (broken links, duplicate titles, thin content), and optionally runs Lighthouse on page samples. The heavy lifting is in SiteAuditWorkflow (src/server/workflows/SiteAuditWorkflow.ts), invoked via the site-audit-tools MCP collection.

import { startAudit } from "@/serverFunctions/siteAudit";

await startAudit({
  projectId: "proj_123",
  startUrl: "https://example.com",
  config: { lighthouseStrategy: "sample", maxPages: 500 },
});

This creates an AuditRepository entry and launches the workflow with configurable crawling limits.

Domain Overview Module

The Domain Overview module provides rapid organic traffic estimates, keyword counts, and backlink summaries for any domain. It serves as the standard first step in domain research workflows.

Implementation is in src/server/mcp/tools/get-domain-overview.ts.

SERP Retrieval Module

The SERP Retrieval module pulls raw Google SERP results — organic listings, local packs, and paid ads — for single queries. This supports "quick SERP peek" functionality and supplies raw ranking data to AI agents.

Found in src/server/mcp/tools/get-serp-results.ts.

Search Console Integration Module

The Search Console Integration module wraps Google Search Console APIs for performance reports and URL inspection. This is a credit-free, read-only module that does not consume DataForSEO credits.

Core files include:

import { getSearchConsolePerformanceTool } from "@/server/mcp/tools/search-console-tools";

const { structuredContent } = await getSearchConsolePerformanceTool.handler({
  projectId: "proj_123",
  startRow: 0,
  rowCount: 20,
});

console.log(structuredContent?.rows?.[0]);

Project and Saved Keyword Management Module

The Project & Saved-Keyword Management module handles CRUD operations for:

  • Projects
  • Saved keyword tags
  • Lists of saved keywords

These are consumed by both the UI and MCP tools that reference user-persisted data. Key files:

MCP Transport Layer Module

The MCP Transport Layer registers all tools under a single HTTP-JSON endpoint that AI agents (Claude Code, Hermes, etc.) can call. This layer injects authentication, credit metering, and unified error handling.

Implementation: src/server/mcp/transport.ts

Billing and Credit Features Module

The Billing & Credit Features module maps each SEO feature (keyword research, rank tracking, backlinks, etc.) to a credit-cost model and enforces organization-level limits.

Found in src/shared/billing-credit-features.ts

Shared Infrastructure Across All Open-SEO Modules

Every module relies on common infrastructure defined in:

Summary

Open-SEO's modular architecture separates concerns into ten distinct modules:

  • Keyword Research — idea generation and volume data via research-keywords.ts
  • Rank Tracking — scheduled SERP monitoring via RankCheckWorkflow.ts
  • Backlinks — profile analysis via dual MCP tools
  • Site Audits — crawling and Lighthouse via SiteAuditWorkflow.ts
  • Domain Overview — quick traffic and authority snapshots
  • SERP Retrieval — raw ranking data extraction
  • Search Console Integration — free GSC data access
  • Project & Saved-Keyword Management — user data persistence
  • MCP Transport Layer — unified agent API surface
  • Billing & Credit Features — usage metering and limits

Each module exposes clean APIs while sharing authentication, credit metering, and telemetry through the common infrastructure layer.

Frequently Asked Questions

What is an MCP tool in Open-SEO?

An MCP (Machine Control Protocol) tool is a standardized function that AI agents can invoke over HTTP-JSON. In Open-SEO, MCP tools wrap each SEO capability — like keyword research or rank tracking — with consistent authentication, input validation, and structured output formatting. The transport layer in src/server/mcp/transport.ts registers all available tools for agent discovery.

Does Open-SEO require DataForSEO credits for all modules?

No. Only modules that query external search data consume credits: Keyword Research, Rank Tracking, Backlinks, Site Audits, Domain Overview, and SERP Retrieval. The Search Console Integration module is credit-free because it reads directly from Google's APIs using stored OAuth credentials.

How do I add a new Open-SEO module?

Create a new MCP tool file in src/server/mcp/tools/, implement the handler function with proper input/output schemas, and register it in src/server/mcp/transport.ts. If the module needs background processing, add a workflow in src/server/workflows/. Finally, map credit costs in src/shared/billing-credit-features.ts if applicable.

Where is rank tracking data stored?

Historical rank data is stored in the rank_tracking database table defined in src/db/schema.ts. The RankCheckWorkflow.ts populates this table on its scheduled interval, and the get-rank-tracker.ts tool queries it through RankTrackingService for retrieval.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →