DataForSEO MCP Server

Model Context Protocol (MCP) server implementation for DataForSEO, enabling AI assistants to interact with selected DataForSEO APIs and obtain SEO data through a standardized interface.

Features

• AI_OPTIMIZATION API: provides data for keyword discovery, conversational optimization, and real-time LLM benchmarking;
• SERP API: real-time Search Engine Results Page (SERP) data for Google, Bing, and Yahoo;
• KEYWORDS_DATA API: keyword research and clickstream data, including search volume, cost-per-click, and other metrics;
• ONPAGE API: allows crawling websites and webpages according to customizable parameters to obtain on-page SEO performance metrics;
• DATAFORSEO LABS API: data on keywords, SERPs, and domains based on DataForSEO's in-house databases and proprietary algorithms;
• BACKLINKS API: comprehensive backlink analysis including referring domains, anchor text distribution, and link quality metrics;
• BUSINESS DATA API: publicly available data on any business entity;
• DOMAIN ANALYTICS API: data on website traffic, technologies, and Whois details;
• CONTENT ANALYSIS API: robust source of data for brand monitoring, sentiment analysis, and citation management;

Prerequisites

• Node.js (v14 or higher)
• DataForSEO API credentials (API login and password)

Installation

1. Clone the repository:

git clone https://github.com/dataforseo/mcp-server-typescript
cd mcp-server-typescript

1. Install dependencies:

npm install

1. Set up environment variables:

# Required
export DATAFORSEO_USERNAME=your_username
export DATAFORSEO_PASSWORD=your_password

# Optional: specify which modules to enable (comma-separated)
# If not set, all modules will be enabled
export ENABLED_MODULES="SERP,KEYWORDS_DATA,ONPAGE,DATAFORSEO_LABS,BACKLINKS,BUSINESS_DATA,DOMAIN_ANALYTICS"

# Optional: specify which prompts in enabled modules are enable too (prompts names, comma-separated)
# If not set, all prompts from enabled modules will be enabled
export ENABLED_PROMPTS="top_3_google_result_domains,top_5_serp_paid_and_organic"

# Optional: enable full API responses
# If not set or set to false, the server will filter and transform API responses to a more concise format
# If set to true, the server will return the full, unmodified API responses
export DATAFORSEO_FULL_RESPONSE="false"

# Optional: enable simple filter schema
# If set to true, a simplified version of the filters schema will be used.
# This is required for ChatGPT APIs or other LLMs that cannot handle nested structures.
export DATAFORSEO_SIMPLE_FILTER="false"

Installation as an NPM Package

You can install the package globally:

npm install -g dataforseo-mcp-server

Or run it directly without installation:

npx dataforseo-mcp-server

Remember to set environment variables before running the command:

# Required environment variables
export DATAFORSEO_USERNAME=your_username
export DATAFORSEO_PASSWORD=your_password

# Run with npx
npx dataforseo-mcp-server

Building and Running

Build the project:

npm run build

Run the server:

# Start local server (direct MCP communication)
npx dataforseo-mcp-server

# Start HTTP server
npx dataforseo-mcp-server http

HTTP Server Configuration

The server runs on port 3000 by default and supports both Basic Authentication and environment variable-based authentication.

To start the HTTP server, run:

npm run http

Authentication Methods

1. Basic Authentication

   • Send requests with Basic Auth header:

   Authorization: Basic <base64-encoded-credentials>
   

   • Credentials format: username:password

2. Environment Variables

   • If no Basic Auth is provided, the server will use credentials from environment variables:

   export DATAFORSEO_USERNAME=your_username
   export DATAFORSEO_PASSWORD=your_password
   # Optional
   export DATAFORSEO_SIMPLE_FILTER="false"
   export DATAFORSEO_FULL_RESPONSE="true"
   

Cloudflare Worker Deployment

The DataForSEO MCP Server can be deployed as a Cloudflare Worker for serverless, edge-distributed access to DataForSEO APIs.

Worker Features

• Edge Distribution: Deploy globally across Cloudflare's edge network
• Serverless: No server management required
• Auto-scaling: Handles traffic spikes automatically
• MCP Protocol Support: Compatible with both Streamable HTTP and SSE transports
• Environment Variables: Secure credential management through Cloudflare dashboard

Quick Start

1. Install Wrangler CLI:

   npm install -g wrangler
   

2. Configure Worker:

   # Login to Cloudflare
   wrangler login
   
   # Set environment variables
   wrangler secret put DATAFORSEO_USERNAME
   wrangler secret put DATAFORSEO_PASSWORD
   

3. Deploy Worker:

   # Build and deploy
   npm run build
   wrangler deploy --main build/index-worker.js
   

Configuration

The worker uses the same environment variables as the standard server:

• DATAFORSEO_USERNAME: Your DataForSEO username
• DATAFORSEO_PASSWORD: Your DataForSEO password
• ENABLED_MODULES: Comma-separated list of modules to enable
• ENABLED_PROMPTS: Comma-separated list of prompt names to enable
• DATAFORSEO_FULL_RESPONSE: Set to "true" for full API responses

Worker Endpoints

Once deployed, your worker will be available at https://your-worker.your-subdomain.workers.dev/ with the following endpoints:

• POST /mcp: Streamable HTTP transport (recommended)
• GET /sse: SSE connection establishment (deprecated)
• POST /messages: SSE message handling (deprecated)
• GET /health: Health check endpoint
• GET /: API documentation page

Advanced Configuration

Edit wrangler.jsonc to customize your deployment:

{
  "name": "dataforseo-mcp-worker",
  "main": "build/index-worker.js",
  "compatibility_date": "2025-07-10",
  "compatibility_flags": ["nodejs_compat"],
  "vars": {
    "ENABLED_MODULES": "SERP,KEYWORDS_DATA,ONPAGE,DATAFORSEO_LABS",
    "ENABLED_PROMPTS":"top_3_google_result_domains,top_5_serp_paid_and_organic"
  }
}

Usage with Claude

After deployment, configure Claude to use your worker:

{
  "name": "DataForSEO",
  "description": "Access DataForSEO APIs via Cloudflare Worker",
  "transport": {
    "type": "http",
    "baseUrl": "https://your-worker.your-subdomain.workers.dev/mcp"
  }
}

Available Modules

The following modules are available to be enabled/disabled:

• AI_OPTIMIZATION: provides data for keyword discovery, conversational optimization, and real-time LLM benchmarking;
• SERP: real-time SERP data for Google, Bing, and Yahoo;
• KEYWORDS_DATA: keyword research and clickstream data;
• ONPAGE: crawl websites and webpages to obtain on-page SEO performance metrics;
• DATAFORSEO_LABS: data on keywords, SERPs, and domains based on DataForSEO's databases and algorithms;
• BACKLINKS: data on inbound links, referring domains and referring pages for any domain, subdomain, or webpage;
• BUSINESS_DATA: based on business reviews and business information publicly shared on the following platforms: Google, Trustpilot, Tripadvisor;
• DOMAIN_ANALYTICS: helps identify all possible technologies used for building websites and offers Whois data;
• CONTENT_ANALYSIS: help you discover citations of the target keyword or brand and analyze the sentiments around it;

Adding New Tools/Modules

Module Structure

Each module corresponds to a specific DataForSEO API:

• AI_OPTIMIZATION: AI Optimization API
• SERP module → SERP API
• KEYWORDS_DATA module → Keywords Data API
• ONPAGE module → OnPage API
• DATAFORSEO_LABS module → DataForSEO Labs API
• BACKLINKS: module → Backlinks API
• BUSINESS_DATA: module → Business Data API
• DOMAIN_ANALYTICS: module → Domain Analytics API
• CONTENT_ANALYSIS: module → Content Analysis API

Implementation Options

You can either:

1. Add a new tool to an existing module
2. Create a completely new module

Adding a New Tool

Here's how to add a new tool to any new or pre-existing module:

// src/code/modules/your-module/tools/your-tool.tool.ts
import { BaseTool } from '../../base.tool';
import { DataForSEOClient } from '../../../client/dataforseo.client';
import { z } from 'zod';

export class YourTool extends BaseTool {
  constructor(private client: DataForSEOClient) {
    super(client);
    // DataForSEO API returns extensive data with many fields, which can be overwhelming
    // for AI agents to process. We select only the most relevant fields to ensure
    // efficient and focused responses.
    this.fields = [
      'title',           // Example: Include the title field
      'description',     // Example: Include the description field
      'url',            // Example: Include the URL field
      // Add more fields as needed
    ];
  }

  getName() {
    return 'your-tool-name';
  }

  getDescription() {
    return 'Description of what your tool does';
  }

  getParams(): z.ZodRawShape {
    return {
      // Required parameters
      keyword: z.string().describe('The keyword to search for'),
      location: z.string().describe('Location in format "City,Region,Country" or just "Country"'),
      
      // Optional parameters
      fields: z.array(z.string()).optional().describe('Specific fields to return i

---