# OpenSEO MCP Server: Complete Guide to AI Agent Tools

> Discover OpenSEO MCP server's 14 AI agent tools for automating SEO tasks like keyword research, backlink analysis, and site audits. Integrate easily via JSON-RPC.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/every-app/open-seo/blob/main/create-project.ts)** — Instantiates a new SEO project with configuration parameters.
- **[`list-projects.ts`](https://github.com/every-app/open-seo/blob/main/list-projects.ts)** — Returns all projects accessible to the authenticated caller.
- **[`whoami.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/research-keywords.ts)** — Queries DataForSEO APIs to generate keyword metrics (search volume, CPC, competition).
- **[`save-keywords.ts`](https://github.com/every-app/open-seo/blob/main/save-keywords.ts)** — Persists keyword collections to the user's saved‑keyword store, associated with a `project_id`.
- **[`list-saved-keywords.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/output-schemas.ts) before execution.

### SERP and Rank Tracking Tools

Monitor search visibility programmatically:

- **[`get-serp-results.ts`](https://github.com/every-app/open-seo/blob/main/get-serp-results.ts)** — Fetches live SERP data for any query/location combination.
- **[`get-rank-tracker.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/get-domain-overview.ts)** — Returns aggregated metrics: traffic estimates, authority score, backlink count, organic keyword footprint.
- **[`get-domain-keyword-suggestions.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/get-backlinks-overview.ts)** — Summarizes totals: referring domains, backlink count, follow/no‑follow ratios.
- **[`get-backlinks-profile.ts`](https://github.com/every-app/open-seo/blob/main/get-backlinks-profile.ts)** — Delivers detailed link‑level data including source URLs, anchor text, and authority scores.

### Site Audit Tools

- **[`site-audit-tools.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts).

### Example: Domain Overview Query

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

```

Response structure:

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

```

### Example: Persisting Keywords

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

```

Confirmation response:

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

```

### Example: Retrieving Saved Keywords

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

```

Returns timestamped collections:

```json
{
  "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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) | HTTP request routing, CORS, auth verification, response formatting |
| [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) | Auth context definition (`openSeoAuth` payload injection) |
| [`src/server/mcp/output-schemas.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/output-schemas.ts) | Zod schemas for runtime type safety of all tool I/O |
| [`src/server/mcp/table.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/table.ts) | Plain‑text table renderer for non‑structured clients |
| [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/transport.ts).
- **Type safety** is enforced through Zod schemas in [`output-schemas.ts`](https://github.com/every-app/open-seo/blob/main/output-schemas.ts), ensuring predictable machine‑to‑machine communication.
- **OAuth authentication** with `MCP_SCOPE` is mandatory, handled by [`oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/oauth-provider.ts) module issues tokens and validates them on every request. The authenticated context is injected via [`context.ts`](https://github.com/every-app/open-seo/blob/main/context.ts) as `openSeoAuth`, accessible to all tool implementations.

### Can AI agents perform keyword research directly through OpenSEO?

Yes. Agents call **[`research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/research-keywords.ts)** to query DataForSEO APIs for volume and competition metrics, then use **[`save-keywords.ts`](https://github.com/every-app/open-seo/blob/main/save-keywords.ts)** to persist results to a project. The **[`dataforseo-research-tools.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/output-schemas.ts). For clients requiring text‑only output, [`table.ts`](https://github.com/every-app/open-seo/blob/main/table.ts) renders results as ASCII tables. All formats maintain the same data fields and type guarantees.