Available MCP Tools for OpenSEO Projects: Complete Reference Guide

OpenSEO exposes 40+ Model Context Protocol (MCP) tools organized into nine functional categories, each defined as a Zod-validated constant in src/server/mcp/tools/ and registered through instrumentMcpToolHandler for AI agent consumption.

OpenSEO (the every-app/open-seo repository) provides a comprehensive MCP interface that allows AI agents to execute SEO workflows programmatically. The available MCP tools for OpenSEO projects cover keyword research, rank tracking, site audits, backlink analysis, and Google Search Console integration, all authenticated via project-scoped credentials and formatted through shared table utilities.

Understanding the MCP Architecture

Every MCP tool in OpenSEO follows a consistent structure defined in src/server/mcp/schemas.ts. Each tool exports a constant suffixed with Tool (e.g., whoamiTool, researchKeywordsTool) containing:

• Zod schemas for input validation (inputSchema) and output typing (outputSchema)
• A description for LLM function calling
• An async handler function receiving a ToolContext object

The instrumentMcpToolHandler wrapper in src/server/mcp/instrumentation.ts augments each handler with error handling, billing telemetry, and logging before registration in the MCP server (src/server/mcp/server.ts). Requests route through POST /mcp (handled in src/server/mcp/transport.ts), authenticate via withMcpProjectAuth in src/server/mcp/project-auth.ts, and format responses using utilities from src/server/mcp/table.ts.

Core and Project Management Tools

These tools handle identity verification and project lifecycle operations:

• whoamiTool – Returns the authenticated user identity. Located in src/server/mcp/tools/whoami.ts.
• createProjectTool – Initializes a new SEO project. Located in src/server/mcp/tools/create-project.ts.
• listProjectsTool – Retrieves all projects for a workspace. Located in src/server/mcp/tools/list-projects.ts.
• getProjectContextTool – Fetches a project's memory context. Located in src/server/mcp/tools/project-context.ts.
• updateProjectContextTool – Generated via buildUpdateProjectContextTool in the same file as above, updating project memory context.

Keyword Research and SERP Analysis

DataForSEO powers these research capabilities:

• researchKeywordsTool – Executes DataForSEO keyword research. Located in src/server/mcp/tools/research-keywords.ts.
• getKeywordMetricsTool – Retrieves volume, difficulty, and CPC data. Located in src/server/mcp/tools/dataforseo-research-tools.ts.
• getDomainKeywordSuggestionsTool – Generates keyword ideas for a specific domain. Located in src/server/mcp/tools/get-domain-keyword-suggestions.ts.
• getDomainOverviewTool – Provides domain-wide keyword metrics. Located in src/server/mcp/tools/get-domain-overview.ts.
• getSerpResultsTool – Fetches live Google SERP results for any query. Located in src/server/mcp/tools/get-serp-results.ts.

Search Console and Google Analytics Integration

Connect to Google Search Console (GSC) and Google Analytics 4 (GA4):

• getSearchConsolePerformanceTool – Pulls GSC performance metrics. Located in src/server/mcp/tools/search-console-tools.ts.
• inspectUrlsTool – Performs URL-level inspection via GSC. Shares the file above.
• getGoogleAnalyticsOrganicLandingPagesTool – GA4 organic landing page data.
• getGoogleAnalyticsPagePerformanceTool – Page-level GA4 metrics.
• getGoogleAnalyticsKeyEventsTool – Conversion and key event tracking.
• getSearchOpportunitiesTool – Identifies search optimization opportunities.
• getGoogleAnalyticsOrganicOverviewTool – High-level organic traffic summary.
• getGoogleAnalyticsTrafficAcquisitionTool – Acquisition channel breakdowns.
• getGoogleAnalyticsEcommercePerformanceTool – E-commerce transaction analysis.
• getGoogleAnalyticsSiteSearchTool – Internal search behavior metrics.
• getGoogleAnalyticsAudienceBreakdownTool – Demographic and interest data.
• getGoogleAnalyticsMeasurementHealthTool – GA4 implementation diagnostics.

All GA4 tools reside in src/server/mcp/tools/google-analytics-tools.ts.

Backlink Analysis Tools

Evaluate domain authority through backlink data:

• getBacklinksOverviewTool – Summarizes backlink counts and authority scores. Located in src/server/mcp/tools/get-backlinks-overview.ts.
• getBacklinksProfileTool – Enumerates individual backlinks for a domain. Located in src/server/mcp/tools/get-backlinks-profile.ts.

Rank Tracking Tools

Manage keyword position monitoring campaigns:

• createRankTrackerTool – Initializes a new rank tracker. Located in src/server/mcp/tools/create-rank-tracker.ts.
• runRankTrackerTool – Triggers a tracking run. Located in src/server/mcp/tools/run-rank-tracker.ts.
• getRankTrackerTool – Retrieves tracker status and results. Located in src/server/mcp/tools/get-rank-tracker.ts.
• addRankTrackingKeywordsTool – Appends keywords to existing trackers. Located in src/server/mcp/tools/add-rank-tracking-keywords.ts.
• removeRankTrackingKeywordsTool – Removes keywords from trackers. Located in src/server/mcp/tools/remove-rank-tracking-keywords.ts.
• estimateRankTrackerCostTool – Calculates cost estimates for tracker runs. Located in src/server/mcp/tools/estimate-rank-tracker-cost.ts.

Local SEO and Business Data

Manage Google Business Profile and local search visibility:

• getBusinessProfileTool – Business profile lookup.
• getBusinessReviewsTool – Recent review retrieval.
• getBusinessUpdatesTool – Latest business post updates.
• listBusinessCategoriesTool – Available business category enumeration.
• getLocalRankGridTool – Local rank grid visualization for specific locations.

All five tools are implemented in src/server/mcp/tools/local-seo-tools.ts.

Site Audit Tools

Technical SEO analysis capabilities:

• runSiteAuditTool – Initiates a site crawl. Located in src/server/mcp/tools/site-audit-tools.ts.
• getAuditStatusTool – Polls audit completion status. Shares the file above.
• getAuditIssuesTool – Retrieves categorized technical issues. Shares the file above.
• getAuditPagesTool – Lists pages affected by specific issues. Shares the file above.

Saved Keywords Management

Persist and manage keyword lists across sessions:

• saveKeywordsTool – Stores keyword sets. Located in src/server/mcp/tools/save-keywords.ts.
• listSavedKeywordsTool – Enumerates saved keyword collections. Located in src/server/mcp/tools/list-saved-keywords.ts.

Calling MCP Tools: Client and Server Examples

Client-Side Request

AI agents or external clients invoke tools via the /mcp endpoint:

const response = await fetch('/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tool: 'getSerpResultsTool',
    args: { 
      query: 'open source SEO', 
      locationCode: 2840, 
      languageCode: 'en' 
    },
    projectId: 'proj_12345'
  })
});
const data = await response.json();

Server-Side Tool Implementation

Tools follow a strict TypeScript interface. Here is the whoamiTool implementation from src/server/mcp/tools/whoami.ts:

import { z } from 'zod';

export const whoamiTool = {
  description: 'Returns the identity of the caller.',
  inputSchema: z.object({}),
  outputSchema: z.object({ userId: z.string() }),
  async handler(_: ToolContext, _args: unknown) {
    return { userId: _.auth.userId };
  },
};

Adding New Tools

To extend the available MCP tools for OpenSEO projects:

1. Create a new file in src/server/mcp/tools/ exporting a constant ending in Tool.
2. Define Zod schemas for inputSchema and outputSchema.
3. Implement the async handler function.
4. Run npm test to validate against src/server/mcp/tools/output-schema-validation.test.ts.

Summary

• OpenSEO provides 40+ MCP tools spanning keyword research, rank tracking, technical audits, and analytics integration.
• Tools are defined as exported constants in src/server/mcp/tools/ with Zod validation schemas.
• The instrumentMcpToolHandler in src/server/mcp/instrumentation.ts wraps handlers for telemetry and error handling.
• Authentication occurs via withMcpProjectAuth in src/server/mcp/project-auth.ts, enforcing project-scoped access.
• Client requests route through POST /mcp handled by src/server/mcp/transport.ts.
• All tools are validated by automated tests in src/server/mcp/tools/output-schema-validation.test.ts.

Frequently Asked Questions

What is the Model Context Protocol (MCP) in OpenSEO?

The Model Context Protocol is a standardized interface that allows AI agents to interact with OpenSEO's functionality through function calls. In the every-app/open-seo repository, MCP tools are TypeScript objects with Zod schemas that validate inputs, execute SEO operations, and return structured data for consumption by LLMs like Claude or Cursor.

How does authentication work for MCP tool calls?

All MCP tools require project-scoped authentication handled by withMcpProjectAuth in src/server/mcp/project-auth.ts. When calling a tool, clients must include a valid projectId in the request body. The server verifies the caller has access to that specific project before executing the handler function.

Can I add custom MCP tools to my OpenSEO instance?

Yes. Create a new file in src/server/mcp/tools/ exporting a tool constant with Zod schemas for input/output validation. The tool automatically registers when the server starts. Run the test suite (npm test) to ensure your implementation passes the output schema validation in src/server/mcp/tools/output-schema-validation.test.ts.

Which external data sources do the MCP tools utilize?

The tools integrate with DataForSEO for keyword research and backlink data, Google Search Console for performance metrics, Google Analytics 4 for traffic analysis, and proprietary crawling infrastructure for SERP results and site audits. Each data source connection is managed through environment-specific credentials configured in the OpenSEO deployment.

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