How to Perform Rank Tracking with OpenSEO's MCP Tools: A Complete 5-Step Guide

OpenSEO implements rank tracking as a suite of typed MCP (Machine-Centric Protocol) tools that enable programmatic monitoring of keyword positions across devices and markets through five logical steps: configuration, keyword ingestion, cost estimation, execution, and retrieval.

OpenSEO provides a fully programmatic rank tracking pipeline through its MCP (Machine-Centric Protocol) architecture, allowing developers and AI agents to monitor search engine rankings without manual intervention. The system leverages DataForSEO's SERP API to capture snapshots while managing credit consumption through built-in safeguards. This guide explains how to perform rank tracking with OpenSEO's MCP tools using the actual TypeScript implementation and validation schemas found in the every-app/open-seo repository.

Understanding the MCP Rank Tracking Architecture

OpenSEO's rank tracking functionality resides in the src/server/mcp/tools/ directory as a set of typed, validated, and version-controlled modules. Each tool exports a JSON schema describing its inputs and outputs, enabling automatic validation by the MCP runtime as tested in src/server/mcp/tools/output-schema-validation.test.ts.

The tools are registered under the "rank tracking" namespace in src/server/mcp/server.ts, making them discoverable by AI agents, the built-in SAM bot, and external automation scripts. Under the hood, rank tracking relies on the DataForSEO SERP API (src/server/mcp/tools/dataforseo-research-tools.ts), while the keyword-location picker (src/shared/keyword-locations.ts) provides supported countries, languages, and device types.

Step 1: Create a Rank Tracking Configuration

The pipeline begins with create-rank-tracker.ts, which instantiates a tracker without consuming credits. This module defines the domain, market, devices, schedule, and optional location parameters.

import { mcpClient } from "./src/server/mcp/client";

// Create a tracker (no keywords yet, no credits consumed)
await mcpClient.invoke("createRankTrackerTool", {
  projectId: "proj_123",
  domain: "example.com",
  market: "us",
  device: "mobile",
  schedule: "weekly",
});

An empty tracker configuration does not incur any credit costs until keywords are added. The configuration persists in the PostgreSQL schema defined in src/db/pg/app.schema.ts.

Step 2: Add Keywords to the Tracker

After initialization, populate the tracker using add-rank-tracking-keywords.ts. This module enforces the soft limit defined in src/shared/rank-tracking.ts, where MAX_KEYWORDS_PER_CONFIG = 500 prevents runaway credit usage.

// Add keywords to the existing tracker
await mcpClient.invoke("addRankTrackingKeywordsTool", {
  trackerId: "track_456",
  keywords: ["open seo", "rank tracking", "mcp tools"],
});

The soft limit of 500 keywords per configuration protects against accidental over-consumption of DataForSEO credits and can be adjusted in the shared constants file.

Step 3: Estimate Credit Costs

Before executing the tracker, calculate projected expenses using estimate-rank-tracker-cost.ts. This tool calls the DataForSEO pricing endpoint to determine credit consumption based on the selected schedule and search depth.

// Calculate projected cost before running
const cost = await mcpClient.invoke("estimateRankTrackerCostTool", {
  trackerId: "track_456",
  schedule: "weekly",
});
console.log(`Estimated credits per week: ${cost.credits}`);

Cost estimation enables budget-aware workflows by exposing pricing data before any live SERP requests are initiated.

Step 4: Run the Tracker

Execute the crawl using run-rank-tracker.ts, which triggers DataForSEO SERP requests for each stored keyword and persists snapshots to the database.

// Trigger the SERP crawl for all keywords
await mcpClient.invoke("runRankTrackerTool", {
  trackerId: "track_456",
  runNow: true,
});

This module handles the actual data collection, storing rank history and SERP snapshots that feed into reporting interfaces.

Step 5: Retrieve Rank Tracking Results

Access current and historical data through get-rank-tracker.ts, which queries the indexed PostgreSQL records for fast UI rendering and API responses.

// Pull the latest snapshot
const snapshot = await mcpClient.invoke("getRankTrackerTool", {
  trackerId: "track_456",
});
console.log("Current position:", snapshot.positions);

The retrieval tool supports both latest snapshots and historical data queries, enabling trend analysis and competitive monitoring.

Quick Start with Seed Scripts

For ad-hoc testing and development, OpenSEO includes a seed script that demonstrates the complete workflow:

npm run seed-rank-tracking   # Executes scripts/seed-rank-tracking.ts

This command runs scripts/seed-rank-tracking.ts, creating a demo tracker with sample keywords to validate your MCP configuration and DataForSEO credentials.

API Integration and Remote Access

While the TypeScript examples use the local MCP client, the same JSON payloads can be sent through the public OpenSEO API endpoint at /api/mcp. This enables rank tracking automation from external services, CI/CD pipelines, or non-TypeScript environments.

All MCP tools enforce schema validation at the runtime boundary, ensuring that AI agents and external scripts cannot invoke tools with malformed parameters. The validation logic is centralized in src/server/mcp/tools/output-schema-validation.test.ts.

Summary

• Five-step workflow: Create configuration → Add keywords → Estimate cost → Run crawler → Retrieve results
• Credit protection: Soft limit of 500 keywords per tracker (MAX_KEYWORDS_PER_CONFIG) and pre-run cost estimation prevent budget overruns
• Implementation location: Core tools reside in src/server/mcp/tools/ with registration in src/server/mcp/server.ts
• Data persistence: Snapshots store in PostgreSQL (src/db/pg/app.schema.ts) with indexing for fast queries
• Global coverage: Keyword locations and devices supported through src/shared/keyword-locations.ts
• AI-ready: JSON schema exports enable automatic validation and discovery by MCP-enabled agents

Frequently Asked Questions

How does OpenSEO prevent unexpected credit consumption when running rank trackers?

OpenSEO implements a dual protection mechanism through the MCP architecture. First, estimate-rank-tracker-cost.ts calls the DataForSEO pricing endpoint before any live execution, displaying projected credit usage. Second, src/shared/rank-tracking.ts enforces MAX_KEYWORDS_PER_CONFIG = 500 as a soft limit to prevent runaway configurations. Additionally, empty trackers consume zero credits until keywords are explicitly added via add-rank-tracking-keywords.ts.

Can I run rank tracking without using the TypeScript MCP client?

Yes. While the examples use the internal mcpClient from src/server/mcp/client, the tools are exposed through the public REST endpoint /api/mcp. External automation scripts, Python services, or CI/CD pipelines can send the same JSON payloads with the trackerId and authentication headers to invoke runRankTrackerTool or getRankTrackerTool remotely.

What is the maximum number of keywords I can track per project?

The default soft limit is 500 keywords per tracker configuration, defined as MAX_KEYWORDS_PER_CONFIG in src/shared/rank-tracking.ts. This limit protects against accidental credit exhaustion and can be adjusted by modifying the constant in the shared module. For larger scale monitoring, create multiple tracker configurations with different market or device segmentations.

How does the MCP runtime validate tool inputs and outputs?

Each rank tracking tool exports a JSON schema describing its parameters and return types. The MCP runtime, implemented in src/server/mcp/server.ts, uses these schemas for automatic validation before execution and after completion. The validation suite in src/server/mcp/tools/output-schema-validation.test.ts ensures that AI agents and external callers cannot invoke tools with malformed data or receive unexpected response structures.

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