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

> Explore the core functions of the Open-SEO MCP server. This technical reference details 46 SEO tools for AI agents, covering keyword research, rank tracking, site audits, and GSC operations.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: api-reference
- Published: 2026-08-21

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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

```bash
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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)) and returns formatted tables plus structured JSON containing volume, KD, and CPC data.

### List Available Projects

```bash
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

```bash
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) ensures every tool receives authenticated user, organization, and billing context via `ToolContext`.
- **Cloudflare-Native**: [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) and [`public-origin.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.