How to Set Up Rank Tracking Using OpenSEO MCP

OpenSEO MCP exposes rank-tracking functionality through JSON-RPC methods that route through Cloudflare Workers to manage configs, keywords, and scheduled SERP checks via the DataForSEO API.

To set up rank tracking using OpenSEO MCP, you interact with the every-app/open-seo repository's Model-Connect-Protocol (MCP) server, which exposes the same backend service layer that powers the web UI. This ensures your automated workflows stay perfectly synchronized with manual operations, sharing identical data models, scheduling logic, and cost estimation formulas.

Understanding the OpenSEO MCP Architecture

The rank-tracking implementation follows a three-tier architecture that separates data persistence, business logic, and protocol handling.

Data Model Layer

The foundation resides in src/shared/rank-tracking.ts, which defines RankTrackingConfig rows storing domain, location, devices, SERP depth, schedule intervals, and next-check timestamps. Keywords live in the rankTrackingKeywords table. This file also exports estimateRankCheckCredits for cost calculations and computeNextCheckAt for drift-free scheduling.

Service Layer

RankTrackingService in src/server/features/rank-tracking/services/RankTrackingService.ts orchestrates the entire workflow. It validates input parameters, enforces plan limits (blocking unpaid projects), creates or updates configurations, triggers rank-check runs, and refreshes keyword metrics after DataForSEO results return.

MCP Entry Points

Each function in src/serverFunctions/rank-tracking.ts becomes an automatic MCP method via createServerFn wrappers. These RPC endpoints—such as createRankTrackingConfig and addTrackingKeywords—serve both the React UI and external MCP clients identically.

Step-by-Step MCP Setup Process

Follow this sequence to configure automated rank monitoring through any MCP-compatible client (Claude Code, Cursor, Codex CLI, or custom HTTP clients).

1. Connect the MCP Endpoint

Configure your client to connect to https://app.openseo.so/mcp. All subsequent requests use JSON-RPC 2.0 over HTTPS with Bearer token authentication using your OpenSEO API key.

2. Create a Rank Tracking Config

Call createRankTrackingConfig to establish the monitoring parameters. This creates a RankTrackingConfig row with your domain, location code, language, device targeting, and schedule interval:

POST https://app.openseo.so/mcp
Content-Type: application/json
Authorization: Bearer oseo_YOUR_API_KEY

{
  "jsonrpc": "2.0",
  "method": "createRankTrackingConfig",
  "params": {
    "projectId": "PROJECT_ID",
    "domain": "example.com",
    "locationCode": 2840,
    "languageCode": "en",
    "devices": "both",
    "serpDepth": 20,
    "scheduleInterval": "weekly"
  },
  "id": 1
}

The response includes the config id and calculated nextCheckAt timestamp based on computeNextCheckAt logic.

3. Add Keywords to Track

Use addTrackingKeywords to populate the configuration. This inserts rows into rankTrackingKeywords and optionally triggers an immediate check depending on your plan:

POST https://app.openseo.so/mcp
Content-Type: application/json
Authorization: Bearer oseo_YOUR_API_KEY

{
  "jsonrpc": "2.0",
  "method": "addTrackingKeywords",
  "params": {
    "projectId": "PROJECT_ID",
    "configId": "CONFIG_ID_FROM_ABOVE",
    "keywords": [
      "seo audit tool",
      "keyword research software",
      "backlink checker"
    ]
  },
  "id": 2
}

4. Estimate Costs Before Checking

Before consuming credits, call estimateRankCheckCost (which internally uses the estimateRankCheckCredits formula from src/shared/rank-tracking.ts):

POST https://app.openseo.so/mcp
Content-Type: application/json
Authorization: Bearer oseo_YOUR_API_KEY

{
  "jsonrpc": "2.0",
  "method": "estimateRankCheckCost",
  "params": {
    "projectId": "PROJECT_ID",
    "configId": "CONFIG_ID_FROM_ABOVE"
  },
  "id": 3
}

The response contains costUsd, costCredits, and monthly projection values based on your schedule frequency and keyword count.

5. Trigger a Manual Rank Check

To execute an immediate SERP scrape rather than waiting for the scheduler, invoke triggerRankCheck. On paid plans, this starts a Cloudflare Workflow (env.RANK_CHECK_WORKFLOW) that batches requests to DataForSEO and stores snapshots in the rankSnapshots table:

POST https://app.openseo.so/mcp
Content-Type: application/json
Authorization: Bearer oseo_YOUR_API_KEY

{
  "jsonrpc": "2.0",
  "method": "triggerRankCheck",
  "params": {
    "projectId": "PROJECT_ID",
    "configId": "CONFIG_ID_FROM_ABOVE",
    "keywordIds": []
  },
  "id": 4
}

Pass an empty keywordIds array to check all keywords associated with the configuration.

Key Implementation Files

Understanding these source files helps debug issues or extend functionality:

• src/shared/rank-tracking.ts – Contains cost formulas, schedule utilities, and the computeNextCheckAt function that prevents scheduling drift.
• src/server/features/rank-tracking/services/RankTrackingService.ts – The core service class handling validation, DataForSEO API orchestration, and plan enforcement.
• src/serverFunctions/rank-tracking.ts – MCP-exposed RPC wrappers including createRankTrackingConfig, addTrackingKeywords, and triggerRankCheck.
• scripts/seed-rank-tracking.ts – Utility script for generating synthetic rank-tracking data useful for local development and testing.
• web/content/docs/mcp.md – Official documentation for adding the OpenSEO MCP server to various agents and IDEs.

Summary

• OpenSEO MCP provides JSON-RPC access to the full rank-tracking stack through https://app.openseo.so/mcp.
• The workflow requires creating a RankTrackingConfig, adding keywords, optionally estimating costs via estimateRankCheckCost, and triggering checks via triggerRankCheck.
• Cost estimation relies on formulas in src/shared/rank-tracking.ts, while scheduling uses computeNextCheckAt to maintain accuracy.
• Cloudflare Workers route MCP requests through RankTrackingService, which enforces plan limits and manages DataForSEO API interactions.
• All MCP methods map 1:1 to server functions in src/serverFunctions/rank-tracking.ts, ensuring UI and API consistency.

Frequently Asked Questions

What authentication is required for OpenSEO MCP requests?

All MCP requests require a Bearer token header using your OpenSEO API key formatted as Authorization: Bearer oseo_YOUR_API_KEY. The service validates this token in the Cloudflare Worker layer before routing to RankTrackingService for project-specific authorization.

How does OpenSEO MCP calculate rank-check costs?

The system uses the estimateRankCheckCredits function defined in src/shared/rank-tracking.ts, which factors in SERP depth, device targeting (desktop, mobile, or both), and keyword volume. The MCP method estimateRankCheckCost exposes this calculation, returning both credit costs and USD equivalents before you commit to a check.

Can I schedule automatic rank checks via MCP?

Yes. When you create a configuration using createRankTrackingConfig, specify a scheduleInterval such as "daily", "weekly", or "monthly". The computeNextCheckAt utility calculates the next execution time, and Cloudflare's cron triggers handle the automation. You can monitor nextCheckAt in the config response to verify scheduling.

What happens when I trigger a rank check on a free plan?

RankTrackingService enforces plan limits before executing checks. If your project lacks a paid subscription, the MCP method will return an authorization error rather than queueing the Cloudflare Workflow or consuming DataForSEO credits. Upgrade to a paid plan to enable automated and manual rank checking via MCP.

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