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

> Learn to perform rank tracking with OpenSEO's MCP tools in 5 easy steps. Monitor keyword positions across devices and markets programmatically. Get the complete guide now.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/output-schema-validation.test.ts).

The tools are registered under the `"rank tracking"` namespace in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/dataforseo-research-tools.ts)), while the keyword-location picker ([`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/create-rank-tracker.ts), which instantiates a tracker without consuming credits. This module defines the domain, market, devices, schedule, and optional location parameters.

```typescript
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`](https://github.com/every-app/open-seo/blob/main/src/db/pg/app.schema.ts).

## Step 2: Add Keywords to the Tracker

After initialization, populate the tracker using [`add-rank-tracking-keywords.ts`](https://github.com/every-app/open-seo/blob/main/add-rank-tracking-keywords.ts). This module enforces the soft limit defined in [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts), where `MAX_KEYWORDS_PER_CONFIG = 500` prevents runaway credit usage.

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/estimate-rank-tracker-cost.ts). This tool calls the DataForSEO pricing endpoint to determine credit consumption based on the selected schedule and search depth.

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/run-rank-tracker.ts), which triggers DataForSEO SERP requests for each stored keyword and persists snapshots to the database.

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/get-rank-tracker.ts), which queries the indexed PostgreSQL records for fast UI rendering and API responses.

```typescript
// 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:

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

```

This command runs [`scripts/seed-rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)
- **Data persistence**: Snapshots store in PostgreSQL ([`src/db/pg/app.schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/pg/app.schema.ts)) with indexing for fast queries
- **Global coverage**: Keyword locations and devices supported through [`src/shared/keyword-locations.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/estimate-rank-tracker-cost.ts) calls the DataForSEO pricing endpoint before any live execution, displaying projected credit usage. Second, [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.