Core Functions of the Open-SEO MCP Server: Complete Technical Reference

The Open-SEO MCP server exposes 46 SEO-focused tools through the Model Context Protocol, enabling AI agents to execute keyword research, rank tracking, site audits, and Google Search Console operations programmatically.

The core functions of the MCP server for open-seo bridge AI agents—including Claude, Cursor, and Codex—with comprehensive SEO operations. Built on the Model Context Protocol (MCP), this TypeScript-based server runs on Cloudflare Workers and provides authenticated access to keyword metrics, backlink analysis, SERP data, and site auditing capabilities through standardized JSON-RPC endpoints.

MCP Server Architecture

The architecture consists of five tightly integrated components that handle everything from transport layer concerns to tool execution context.

Server Initialization and Metadata

The createOpenSeoMcpServer function instantiates the MCP server instance with descriptive metadata (name, version, description, icons) and usage instructions. Located in src/server/mcp/server.ts (lines 1–35), this initialization defines the /mcp endpoint that advertises available tools to any compliant MCP client.

Tool Registration System

Each SEO capability is wrapped as an OpenSeoToolDefinition and registered via registerOpenSeoTool (lines 99–102 and 155–200 in src/server/mcp/server.ts). This registration system normalizes input and output schemas using Zod validation, injects authentication context automatically, and instruments handlers for telemetry tracking.

Authentication and Context Injection

The src/server/mcp/context.ts file (lines 6–15, 63–84) extracts OAuth-verified user credentials, organization details, and project information to build a ToolContext object. Every registered tool receives this context, ensuring operations execute under the correct user/organization scope with proper billing attribution.

Public Origin Handling

When deployed behind Cloudflare Workers, src/server/mcp/public-origin.ts (lines 10–28) rewrites incoming requests to report the correct public URL (https://app.openseo.so/mcp). This middleware ensures MCP clients receive valid endpoint references regardless of internal routing.

HTTP Transport Layer

The createMcpHandler function in src/server/mcp/transport.ts (lines 1–22) builds the HTTP handler, binding the server to the Cloudflare Workers runtime. This layer manages CORS headers, OPTIONS preflight requests, and authentication verification before passing requests to the MCP server instance.

SEO Tool Categories

The server registers 46 concrete tools organized into logical groups that cover the full SEO workflow spectrum.

Identity and Project Management

• whoamiTool (line 155): Returns the caller’s user ID, organization ID, and project ID for context verification.
• listProjectsTool, createProjectTool, getProjectContextTool, updateProjectContextTool (lines 156–159): Provide full CRUD operations for Open-SEO projects, including dashboard URL generation.

Keyword Research and Metrics

• listSavedKeywordsTool, researchKeywordsTool, saveKeywordsTool (lines 160–162): Enable reading, researching, and persisting keyword lists.
• getKeywordMetricsTool (line 185): Hydrates up to 700 keywords with search volume, keyword difficulty (KD), CPC, competition level, and trends data via DataForSEO integration.

Domain and Backlink Analysis

• getDomainOverviewTool, getDomainKeywordSuggestionsTool (lines 163–164): Pull comprehensive domain-level SEO metrics and keyword opportunities.
• getBacklinksOverviewTool, getBacklinksProfileTool (lines 165–166): Analyze backlink profiles, referring domains, and anchor text distributions.

SERP and Local Search Operations

This category includes 10 specialized tools (lines 167–182):

• getSerpResultsTool: Fetches real-time Google SERP results for any keyword.
• getLocalSerpResultsTool and searchLocalBusinessesTool: Retrieve local map pack and business listings.
• getGoogleBusinessQuestionsTool, getBusinessProfileTool, getBusinessReviewsTool: Extract Google Business Profile Q&A, details, and review data.
• getLocalRankGridTool: Generates geo-grid ranking reports for local SEO tracking.

Rank Tracking Workflow

Seven dedicated tools manage rank tracking campaigns (lines 168–174):

• createRankTrackerTool and getRankTrackerTool: Configure and query rank tracking jobs.
• addRankTrackingKeywordsTool and removeRankTrackingKeywordsTool: Modify keyword lists within existing trackers.
• estimateRankTrackerCostTool: Calculate credit costs before execution.
• runRankTrackerTool: Execute the actual rank tracking crawl (credit-charged operation).
• getRankedKeywordsTool: Retrieve current and historical ranking positions.

Google Search Console Integration

• getSearchConsolePerformanceTool (line 185): Queries GSC performance data including clicks, impressions, CTR, and average position.
• inspectUrlsTool (line 186): Runs URL inspection API calls to check indexing status and mobile usability.

Google Analytics 4 Support

Ten distinct tools (lines 187–196) provide access to GA4 data:

• Audience demographics and acquisition channels
• E-commerce transaction and revenue metrics
• Site-search query analysis
• Technical health monitoring and core web vitals

Site Audit Capabilities

Four tools handle technical SEO auditing (lines 197–200):

• runSiteAuditTool: Initiates a comprehensive site crawl.
• getAuditStatusTool: Monitors audit progress and completion states.
• getAuditIssuesTool: Returns categorized technical issues (broken links, duplicate content, schema errors).
• getAuditPagesTool: Provides page-level audit findings and recommendations.

Request Execution Flow

Understanding how requests flow through the system clarifies how the core functions operate under the hood:

1. HTTP Ingress: Cloudflare Workers receives the request and transport.createMcpHandler processes CORS and origin correction via public-origin.ts.
2. Authentication: The worker extracts the MCP_AUTH_CONTEXT_PROP marker and constructs an McpProps object containing verified credentials.
3. Method Routing: The McpServer matches the JSON-RPC "method" field to a registered tool name (e.g., "get_keyword_metrics").
4. Schema Validation: Zod validates input parameters against the tool's inputSchema definition.
5. Context Assembly: createMcpToolContext injects auth, billing, and project data into a ToolContext instance.
6. Handler Execution: The tool's handler executes, typically calling DataForSEO APIs, Google APIs, or internal databases.
7. Response Formatting: mcpResponse wraps results with human-readable markdown text, meta links to the Open-SEO dashboard, and structured JSON payloads.

Practical Implementation Examples

The following curl commands demonstrate how MCP clients interact with the server endpoints.

Retrieve Keyword Metrics

curl -X POST https://app.openseo.so/mcp \
  -H "Authorization: Bearer YOUR_OPENSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "method": "get_keyword_metrics",
        "params": {
          "projectId": "proj_123",
          "keywords": ["open source seo", "mcp server"],
          "locationCode": 2840,
          "languageCode": "en",
          "includeMonthlyTrends": false,
          "sortBy": "search_volume"
        },
        "id": 1
      }'

This invokes getKeywordMetricsTool (registered at line 185 in src/server/mcp/server.ts) and returns formatted tables plus structured JSON containing volume, KD, and CPC data.

List Available Projects

curl -X POST https://app.openseo.so/mcp \
  -H "Authorization: Bearer YOUR_OPENSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "method": "list_projects",
        "params": {},
        "id": 2
      }'

Handled by listProjectsTool (line 156), this returns project IDs, names, and associated dashboard URLs scoped to the authenticated user.

Execute Rank Tracking

curl -X POST https://app.openseo.so/mcp \
  -H "Authorization: Bearer YOUR_OPENSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "method": "run_rank_tracker",
        "params": {
          "projectId": "proj_123",
          "rankTrackerId": "rt_456",
          "maxPages": 100
        },
        "id": 3
      }'

This triggers runRankTrackerTool (line 173) to start a credit-charged crawling operation, returning a status URL for monitoring progress.

Summary

• Centralized Server: src/server/mcp/server.ts defines the MCP instance and registers all 46 SEO tools through createOpenSeoMcpServer and registerOpenSeoTool.
• Context-Aware Execution: src/server/mcp/context.ts ensures every tool receives authenticated user, organization, and billing context via ToolContext.
• Cloudflare-Native: src/server/mcp/transport.ts and public-origin.ts optimize the server for edge deployment with proper CORS and origin handling.
• Comprehensive SEO Coverage: Tools span keyword research, rank tracking, backlink analysis, SERP monitoring, Google Search Console, Google Analytics 4, and technical site auditing.
• Type-Safe Interface: All tools use Zod schemas for input validation and return structured JSON with human-readable markdown via mcpResponse.

Frequently Asked Questions

What is the Model Context Protocol in Open-SEO?

The Model Context Protocol (MCP) is an open standard that allows AI agents to discover and call external tools as native functions. In the Open-SEO implementation, the MCP server exposes 46 SEO-specific operations—such as keyword research and rank tracking—through a standardized JSON-RPC interface, enabling Claude, Cursor, and other MCP clients to execute real SEO workflows without leaving their conversational context.

How does authentication work with the Open-SEO MCP server?

Authentication uses OAuth 2.0 Bearer tokens passed in the Authorization header. The src/server/mcp/context.ts file extracts the verified user identity and builds a ToolContext containing the user ID, organization ID, active project, and billing preferences. This context is injected into every tool handler, ensuring all operations respect organizational boundaries and consume credits from the correct account.

Which external data sources does the Open-SEO MCP server integrate with?

According to the source code in src/server/mcp/tools/, the server integrates with DataForSEO for keyword metrics and backlink data, Google Search Console API for performance and URL inspection data, and Google Analytics 4 for audience and conversion metrics. These integrations power tools like getKeywordMetricsTool, getSearchConsolePerformanceTool, and the ten Google Analytics tools registered in the server configuration.

Can I extend the Open-SEO MCP server with custom tools?

Yes. The architecture supports extension through the OpenSeoToolDefinition interface and registerOpenSeoTool function in src/server/mcp/server.ts. New tools must define a Zod input schema, implement a handler function that accepts ToolContext, and return data via mcpResponse for consistent formatting. The modular structure in src/server/mcp/tools/ allows additional tool files to be imported and registered alongside the existing 46 core functions.

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