How to Set Up the OpenSEO MCP Server Locally for Development

To set up the OpenSEO MCP server locally, enable Corepack, install dependencies with pnpm, run database migrations, configure your .env.local file with DataForSEO credentials, and launch the development server with pnpm dev:agents to expose the endpoint at http://open-seo.localhost:1355/mcp.

The Model-Connector-Protocol (MCP) server in the every-app/open-seo repository is a thin HTTP layer that exposes SEO tools—such as keyword research, SERP lookup, and backlink analysis—to AI clients like Claude, Cursor, or Codex. When running the project locally, the MCP endpoint is served by the same Cloudflare Worker that powers the UI, allowing you to develop and test SEO automation workflows on your machine.

OpenSEO MCP Server Architecture

The MCP implementation follows a modular architecture where the core server registers tools and the transport layer handles HTTP communication.

• src/server/mcp/server.ts – Instantiates the McpServer, registers all SEO tools (e.g., researchKeywordsTool, getDomainOverviewTool), and supplies metadata including icons and descriptions.
• src/server/mcp/transport.ts – Creates the HTTP handler that converts incoming requests into MCP calls, adds CORS headers, and injects authentication context for Cloudflare Workers or local development.
• src/server/mcp/tools/ – Contains individual tool implementations following the signature (args, context) => CallToolResult.
• src/server/mcp/context.ts and src/server/mcp/project-auth.ts – Manage the projectId requirement and respect the AUTH_MODE environment variable (cloudflare, local, or hosted).

Because the MCP server shares the same database as the UI, any projects or saved keywords created through the web interface are immediately visible to MCP clients.

Prerequisites

Before starting, ensure you have the following:

• Node.js 20 or later – The project uses native corepack to manage PNPM.
• Corepack – Bundled with Node 24; install separately if using Node 25+.
• DataForSEO credentials – Required for tools that query the DataForSEO API (keyword research, domain overview).

Full requirements are documented in docs/LOCAL_DEVELOPMENT.md.

Local Setup Steps

Follow these steps to configure your local development environment:

1. Enable the exact PNPM version declared in package.json:

   corepack enable

2. Install dependencies using a frozen lockfile to guarantee reproducibility:

   pnpm install --frozen-lockfile

3. Prepare the local database the first time you run the repository:

   pnpm run db:migrate:local

4. Create a local environment file and add your DataForSEO API key. First, base64-encode your credentials (login:password), then add them to the file:

   cp .env.example .env.local
   # Encode credentials: printf '%s' 'YOUR_LOGIN:YOUR_PASSWORD' | base64
   

   Set the authentication mode for local development:

   # Inside .env.local
   
   AUTH_MODE=local_noauth
   DATAFORSEO_API_KEY=your_base64_encoded_credentials

5. Start the development server using Portless, which exposes the worker on a deterministic subdomain:

   pnpm dev:agents

   By default, the MCP endpoint is reachable at http://open-seo.localhost:1355/mcp. If using a Git worktree, Portless prefixes the branch name (e.g., http://feature-x.open-seo.localhost:1355/mcp).

Connecting AI Clients to the Local MCP

Once the server is running, configure your AI client to point to the local endpoint.

Claude Code (CLI)

claude mcp add --transport http --scope user openseo http://open-seo.localhost:1355/mcp

Cursor

Add a custom MCP server in mcp.json via Settings → Tools & Integrations → MCP Tools:

{
  "mcpServers": {
    "openseo": {
      "url": "http://open-seo.localhost:1355/mcp"
    }
  }
}

Codex CLI

codex mcp add openseo --url http://open-seo.localhost:1355/mcp

All three clients will prompt you to log in to OpenSEO. Since the UI is running locally, the OAuth flow resolves to the same instance. For headless authentication, generate an API key in the OpenSEO app settings and pass it as a bearer token.

Testing the MCP Endpoint

Verify your setup by calling a tool directly via HTTP. The following Node.js script invokes the researchKeywordsTool:

import fetch from 'node-fetch';

const MCP_URL = 'http://open-seo.localhost:1355/mcp';
const TOOL_NAME = 'researchKeywords';
const payload = {
  name: TOOL_NAME,
  input: { keywords: ['open source seo'] },
};

const resp = await fetch(`${MCP_URL}/${TOOL_NAME}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // No auth header required when AUTH_MODE=local_noauth
  },
  body: JSON.stringify(payload),
});

const result = await resp.json();
console.log(JSON.stringify(result, null, 2));

Running this script while the dev server is active returns keyword research results in the standard MCP response format.

Troubleshooting Common Issues

Symptom	Likely Cause	Resolution
"Cannot connect – connection refused"	Dev server not running or URL typo	Verify the Portless host matches open-seo.localhost:1355/mcp
"Authorization server response missing required issuer" (Codex)	Codex client version incompatible with OAuth callback	Upgrade Codex CLI to version 0.147.0 or later, or use API-key authentication
"Project not found"	Missing projectId in request context	Use the listProjects tool first to retrieve a valid project ID, then pass it to subsequent tool calls

Additional troubleshooting steps are available in docs/mcp.md.

Summary

• The OpenSEO MCP server is defined in src/server/mcp/server.ts and exposes SEO tools via src/server/mcp/transport.ts at the /mcp endpoint.
• Local development requires Node.js 20+, Corepack, DataForSEO credentials, and the AUTH_MODE=local_noauth environment variable.
• Start the server with pnpm dev:agents to expose http://open-seo.localhost:1355/mcp through Portless.
• AI clients connect via HTTP transport; Claude, Cursor, and Codex all support the local endpoint with simple configuration commands.
• The MCP server shares state with the local UI database, enabling immediate feedback between web interface changes and tool responses.

Frequently Asked Questions

What is the default URL for the local OpenSEO MCP server?

The default URL is http://open-seo.localhost:1355/mcp. This endpoint is exposed by the Portless development server when you run pnpm dev:agents. If you are working in a Git worktree, the URL includes your branch name as a subdomain prefix.

Why does the MCP server require DataForSEO credentials?

Many tools in the OpenSEO catalog—such as researchKeywordsTool and getDomainOverviewTool— rely on the DataForSEO API to fetch live search data. You must provide a base64-encoded login:password string as DATAFORSEO_API_KEY in your .env.local file, or these tools will fail with authentication errors.

Can I use the MCP server without authentication in local development?

Yes. Set AUTH_MODE=local_noauth in your .env.local file. This mode bypasses OAuth checks while still requiring a valid projectId for tool calls. For production or shared environments, use API-key authentication or the full OAuth flow as documented in docs/mcp.md.

How do I find my project ID for MCP tool calls?

Use the listProjects tool via the MCP endpoint or create a project through the local UI at http://open-seo.localhost:1355. The MCP server shares the same SQLite database as the web interface, so any project created in the browser is immediately available to AI clients calling the local MCP server.

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