# How to Set Up Rank Tracking Using OpenSEO MCP

> Learn how to set up rank tracking with OpenSEO MCP. This guide details using JSON-RPC methods and Cloudflare Workers with the DataForSEO API for efficient SERP checks and keyword management.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```json
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:

```json
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`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts)):

```json
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:

```json
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/rank-tracking.ts)** – MCP-exposed RPC wrappers including `createRankTrackingConfig`, `addTrackingKeywords`, and `triggerRankCheck`.
- **[`scripts/seed-rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/scripts/seed-rank-tracking.ts)** – Utility script for generating synthetic rank-tracking data useful for local development and testing.
- **[`web/content/docs/mcp.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.