OpenSEO MCP Server: Complete Guide to AI Agent Tools

OpenSEO exposes 14 MCP tools across 7 categories that AI agents can invoke via JSON‑RPC to automate SEO workflows including project management, keyword research, SERP retrieval, backlink analysis, and site audits.

The MCP (Machine‑Controlled Platform) server in the every-app/open-seo repository provides a standardized interface for AI agents to execute SEO operations programmatically. Each tool is implemented as a TypeScript module under src/server/mcp/tools/ and routed through the central MCP endpoint (/mcp).

MCP Tool Categories and Available Functions

Project Management Tools

AI agents can create and manage SEO projects through three core utilities:

• create-project.ts — Instantiates a new SEO project with configuration parameters.
• list-projects.ts — Returns all projects accessible to the authenticated caller.
• whoami.ts — Verifies the authenticated identity of the MCP client, returning user metadata and permissions.

These tools share the OAuth context defined in src/server/mcp/context.ts, which injects openSeoAuth into every request.

Keyword Research and Storage Tools

The keyword stack enables end‑to‑end research workflows:

• research-keywords.ts — Queries DataForSEO APIs to generate keyword metrics (search volume, CPC, competition).
• save-keywords.ts — Persists keyword collections to the user's saved‑keyword store, associated with a project_id.
• list-saved-keywords.ts — Retrieves stored keywords with metadata including saved_at timestamps.

All keyword tools validate input against Zod schemas in src/server/mcp/output-schemas.ts before execution.

SERP and Rank Tracking Tools

Monitor search visibility programmatically:

• get-serp-results.ts — Fetches live SERP data for any query/location combination.
• get-rank-tracker.ts — Accesses historical rank‑tracking data for keywords under active monitoring.

These tools support localization via language_code and location_code parameters.

Domain Intelligence Tools

Evaluate competitor or client domains with:

• get-domain-overview.ts — Returns aggregated metrics: traffic estimates, authority score, backlink count, organic keyword footprint.
• get-domain-keyword-suggestions.ts — Generates content‑gap keyword ideas based on a domain's existing rankings.

Backlink Analysis Tools

Two granularities of link data:

• get-backlinks-overview.ts — Summarizes totals: referring domains, backlink count, follow/no‑follow ratios.
• get-backlinks-profile.ts — Delivers detailed link‑level data including source URLs, anchor text, and authority scores.

Site Audit Tools

• site-audit-tools.ts — Executes comprehensive technical SEO crawls, returning issues categorized by severity (critical, warning, notice) with remediation guidance.

Google Search Console Integration

• search-console-tools.ts — Bridges GSC data into agent workflows, supporting queries for search impressions, clicks, CTR, and average position over custom date ranges.

DataForSEO Bridge

• dataforseo-research-tools.ts — Low‑level API wrappers that higher‑level tools consume; directly accessible for custom research pipelines.

How AI Agents Call OpenSEO MCP Tools

The MCP transport layer (src/server/mcp/transport.ts) handles all requests via JSON‑RPC 2.0. Agents authenticate using OAuth tokens scoped with MCP_SCOPE, enforced by src/server/mcp/oauth-provider.ts.

Example: Domain Overview Query

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "get_domain_overview",
  "params": {
    "domain": "example.com",
    "language_code": "en"
  }
}

Response structure:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "domain": "example.com",
    "traffic": 12500,
    "authority_score": 72,
    "backlinks": 3421,
    "organic_keywords": 87
  }
}

Example: Persisting Keywords

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "save_keywords",
  "params": {
    "project_id": "proj_123",
    "keywords": ["cloud hosting", "serverless SEO"]
  }
}

Confirmation response:

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "status": "saved",
    "count": 2
  }
}

Example: Retrieving Saved Keywords

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "list_saved_keywords",
  "params": { "project_id": "proj_123" }
}

Returns timestamped collections:

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": [
    { "keyword": "cloud hosting", "saved_at": "2024-09-01T12:34:00Z" },
    { "keyword": "serverless SEO", "saved_at": "2024-09-01T12:35:00Z" }
  ]
}

Core MCP Infrastructure Files

File	Responsibility
src/server/mcp/transport.ts	HTTP request routing, CORS, auth verification, response formatting
src/server/mcp/context.ts	Auth context definition (openSeoAuth payload injection)
src/server/mcp/output-schemas.ts	Zod schemas for runtime type safety of all tool I/O
src/server/mcp/table.ts	Plain‑text table renderer for non‑structured clients
src/server/mcp/oauth-provider.ts	Token issuance and MCP_SCOPE enforcement

Summary

• 14 MCP tools are available via src/server/mcp/tools/, covering project management, keywords, SERP, domains, backlinks, site audits, GSC, and DataForSEO.
• JSON‑RPC 2.0 is the required protocol; all requests route through /mcp and are validated by transport.ts.
• Type safety is enforced through Zod schemas in output-schemas.ts, ensuring predictable machine‑to‑machine communication.
• OAuth authentication with MCP_SCOPE is mandatory, handled by oauth-provider.ts.

Frequently Asked Questions

What protocol do OpenSEO MCP tools use?

OpenSEO MCP tools use JSON‑RPC 2.0 over HTTP. The transport.ts handler parses requests, validates OAuth tokens, routes to the appropriate tool in src/server/mcp/tools/, and returns structured JSON responses.

How does authentication work for MCP clients?

Clients authenticate via OAuth 2.0 tokens with the MCP_SCOPE scope. The oauth-provider.ts module issues tokens and validates them on every request. The authenticated context is injected via context.ts as openSeoAuth, accessible to all tool implementations.

Can AI agents perform keyword research directly through OpenSEO?

Yes. Agents call research-keywords.ts to query DataForSEO APIs for volume and competition metrics, then use save-keywords.ts to persist results to a project. The dataforseo-research-tools.ts module provides lower‑level access for custom research pipelines.

What output formats does the MCP server support?

The primary format is structured JSON defined by Zod schemas in output-schemas.ts. For clients requiring text‑only output, table.ts renders results as ASCII tables. All formats maintain the same data fields and type guarantees.

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