Dataforseo MCP Proxy

DataForSEO MCP服务器

DataForSEO的模型上下文协议（MCP）服务器实现，使AI助手能够与选定的DataForSEO API交互，并通过标准化的接口获取SEO数据。

特性

• AI_OPTMIZATION API（启用API）：为关键字发现、会话优化和实时LLM基准测试提供数据；
• SERP API：谷歌、必应和雅虎的实时搜索引擎结果页面（SERP）数据；
• 关键字_DATA API关键词研究和点击流数据，包括搜索量、每次点击成本和其他指标；
• 首页API：允许根据可定制的参数抓取网站和网页，以获得页面上的SEO性能指标；
• DATAFORSEO实验室API：基于DataForSEO内部数据库和专有算法的关键字、SERP和域名数据；
• API背链：全面的反向链接分析，包括引用域、锚文本分布和链接质量指标；
• API商业数据：任何商业实体的公开数据；
• 领域分析API：网站流量、技术和Whois详细信息的数据；
• 内容分析API：用于品牌监测、情感分析和引文管理的强大数据来源；

先决条件

• Node.js（v14或更高版本）
• DataForSEO API凭据（API登录名和密码）

安装

1. 克隆存储库：

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

1. 安装依赖项：

npm install

1. 设置环境变量：

# 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"

作为NPM包安装

您可以全局安装该软件包：

npm install -g dataforseo-mcp-server

或者直接运行它而不安装：

npx dataforseo-mcp-server

请记住在运行命令之前设置环境变量：

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

# Run with npx
npx dataforseo-mcp-server

建立和运行

构建项目：

npm run build

运行服务器：

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

# Start HTTP server
npx dataforseo-mcp-server http

HTTP服务器配置

默认情况下，服务器在端口3000上运行，支持基本身份验证和基于环境变量的身份验证。

要启动HTTP服务器，请运行：

npm run http

身份验证方法

1. 基本认证

- 使用Basic Auth标头发送请求：

   Authorization: Basic 

- 凭据格式： username:password

1. 环境变量

- 如果没有提供基本身份验证，服务器将使用环境变量中的凭据：

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

Cloudflare工作部署

DataForSEO MCP服务器可以部署为Cloudflare Worker，用于无服务器、边缘分布式访问DataForSEO API。

工人特征

• 边缘分布：在Cloudflare的边缘网络上进行全球部署
• 无服务器：不需要服务器管理
• 自动缩放：自动处理流量峰值
• MCP协议支持：兼容流式HTTP和SSE传输
• 环境变量：通过Cloudflare仪表板进行安全的凭据管理

快速开始

1. 安装牧马人CLI:

   npm install -g wrangler

1. 配置Worker:

   # Login to Cloudflare
   wrangler login

   # Set environment variables
   wrangler secret put DATAFORSEO_USERNAME
   wrangler secret put DATAFORSEO_PASSWORD

1. 部署工作人员:

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

配置

worker使用与标准服务器相同的环境变量：

• DATAFORSEO_USERNAME：您的DataForSEO用户名
• DATAFORSEO_PASSWORD：您的DataForSEO密码
• ENABLED_MODULES：要启用的以逗号分隔的模块列表
• ENABLED_PROMPTS：要启用的逗号分隔的提示名称列表
• DATAFORSEO_FULL_RESPONSE：对于完整的API响应，设置为“true”

工人端点

部署后，您的员工将可在 https://your-worker.your-subdomain.workers.dev/ 具有以下端点：

• POST/mcp：流式HTTP传输（推荐）
• GET/sse：SSE连接建立（已弃用）
• POST/消息：SSE消息处理（已弃用）
• GET/健康：健康检查端点
• 得到/：API文档页

高级配置

编辑 wrangler.jsonc 要自定义部署，请执行以下操作：

{
  "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"
  }
}

与Claude一起使用

部署后，配置Claude以使用您的worker：

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

可用模块

以下模块可供启用/禁用：

• AI_OPTIMIZATION：为关键字发现、会话优化和实时LLM基准测试提供数据；
• SERP：谷歌、必应和雅虎的实时SERP数据；
• KEYWORDS_DATA：关键词研究和点击流数据；
• ONPAGE：抓取网站和网页，以获取页面SEO性能指标；
• DATAFORSEO_LABS：基于DataForSEO数据库和算法的关键字、SERP和域名数据；
• BACKLINKS：任何域、子域或网页的入站链接、引用域和引用页面的数据；
• BUSINESS_DATA：基于以下平台上公开共享的商业评论和商业信息：谷歌、Trustpilot、Tripadvisor；
• DOMAIN_ANALYTICS：帮助识别用于构建网站的所有可能技术，并提供Whois数据；
• CONTENT_ANALYSIS：帮助您发现目标关键字或品牌的引用，并分析围绕它的情绪；

添加新工具/模块

模块结构

每个模块对应一个特定的DataForSEO API：

• AI_OPTIMIZATION: 人工智能优化API
• SERP 模块→ SERP API
• KEYWORDS_DATA 模块→ 关键词数据API
• ONPAGE 模块→ 第页API
• DATAFORSEO_LABS 模块→ DataForSEO实验室API
• BACKLINKS：模块→ 反向链接API
• BUSINESS_DATA：模块→ 业务数据API
• DOMAIN_ANALYTICS：模块→ 域分析API
• CONTENT_ANALYSIS：模块→ 内容分析API

实施方案

您可以：

1. 向现有模块添加新工具
2. 创建一个全新的模块

添加新工具

以下是如何将新工具添加到任何新的或预先存在的模块中：

// 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 in the response. If not specified, all fields will be returned'),
      language: z.string().optional().describe('Language code (e.g., "en")'),
    };
  }

  async handle(params: any) {
    try {
      // Make the API call
      const response = await this.client.makeRequest({
        endpoint: '/v3/dataforseo_endpoint_path',
        method: 'POST',
        body: [{
          // Your request parameters
          keyword: params.keyword,
          location: params.location,
          language: params.language,
        }],
      });

      // Validate the response for errors
      this.validateResponse(response);

      //if the main data array is specified in tasks[0].result[:] field
      const result = this.handleDirectResult(response);
      //if main data array specified in tasks[0].result[0].items field
      const result = this.handleItemsResult(response);
      // Format and return the response
      return this.formatResponse(result);
    } catch (error) {
      // Handle and format any errors
      return this.formatErrorResponse(error);
    }
  }
}

创建新模块

1. 在下创建新目录 src/core/modules/ 对于您的模块：

mkdir -p src/core/modules/your-module-name

1. 创建模块文件：

// src/core/modules/your-module-name/your-module-name.module.ts
import { BaseModule } from '../base.module';
import { DataForSEOClient } from '../../client/dataforseo.client';
import { YourTool } from './tools/your-tool.tool';

export class YourModuleNameModule extends BaseModule {
  constructor(private client: DataForSEOClient) {
    super();
  }

  getTools() {
    return {
      'your-tool-name': new YourTool(this.client),
    };
  }
}

1. 在中注册您的模块 src/core/config/modules.config.ts:

export const AVAILABLE_MODULES = [
  'SERP',
  'KEYWORDS_DATA',
  'ONPAGE',
  'DATAFORSEO_LABS',
  'BACKLINKS',
  'BUSINESS_DATA',
  'DOMAIN_ANALYTICS',
  'CONTENT_ANALYSIS',
  'YOUR_MODULE_NAME'  // Add your module name here
] as const;

1. 在中初始化您的模块 src/main/index.ts:

if (isModuleEnabled('YOUR_MODULE_NAME', enabledModules)) {
  modules.push(new YourModuleNameModule(dataForSEOClient));
}

字段配置

MCP服务器支持字段过滤，以自定义API响应中返回的数据字段。这有助于减少响应大小，并专注于与您的用例最相关的数据。

配置文件格式

创建具有以下结构的JSON配置文件：

{
  "supported_fields": {
    "tool_name": ["field1", "field2", "field3"],
    "another_tool": ["field1", "field2"]
  }
}

使用现场配置

使用传递配置文件 --configuration 参数：

# With npm
npm run cli -- http --configuration field-config.json

# With npx
npx dataforseo-mcp-server http --configuration field-config.json

# Local mode
npx dataforseo-mcp-server local --configuration field-config.json

配置行为

• 如果配置了工具：响应中只会返回指定的字段
• 如果未配置工具：将返回所有可用字段（默认行为）
• 如果没有提供配置文件：所有工具返回所有可用字段

配置文件示例

存储库包括一个示例配置文件 field-config.example.json 对常用工具的字段选择进行了优化：

{
  "supported_fields": {
    "backlinks_backlinks": [
      "id",
      "items.anchor",
      "items.backlink_spam_score",
      "items.dofollow",
      "items.domain_from",
      "items.domain_from_country",
      "items.domain_from_ip",
      "items.domain_from_platform_type",
      "items.domain_from_rank",
      "items.domain_to",
      "items.first_seen",
      "items.is_broken",
      "items.is_new",
      "items.item_type",
      "items.last_seen",
      "items.links_count",
      "items.original",
      "items.page_from_encoding",
      "items.page_from_external_links",
      "items.page_from_internal_links",
      "items.page_from_language",
      "items.page_from_rank",
      "items.page_from_size",
      "items.page_from_status_code",
      "items.page_from_title",
      "items.prev_seen",
      "items.rank",
      "items.ranked_keywords_info.page_from_keywords_count_top_10",
      "items.ranked_keywords_info.page_from_keywords_count_top_100",
      "items.ranked_keywords_info.page_from_keywords_count_top_3",
      "items.semantic_location",
      "items.text_post",
      "items.text_pre",
      "items.tld_from",
      "items.type",
      "items.url_from",
      "items.url_from_https",
      "items.url_to",
      "items.url_to_https",
      "items.url_to_spam_score",
      "items.url_to_status_code",
      "status_code",
      "status_message"
    ],
    ...
  }
}

嵌套现场支持

该配置支持使用点符号的嵌套字段路径：

• "rating.value" -访问 value 场内 rating 对象
• "items.demography.age.keyword" -访问深度嵌套的字段
• "meta.description" -访问嵌套对象属性

领域发现

要查找任何工具的可用字段，请执行以下操作：

1. 运行该工具而不进行字段配置，以查看完整响应
2. 从API响应中确定您需要的字段
3. 将这些字段路径添加到配置文件中

创建自己的配置

1. 复制示例文件：

cp field-config.example.json my-config.json

1. 根据您的需要修改字段选择

1. 使用您的自定义配置：

npx dataforseo-mcp-server http --configuration my-config.json

您希望我们接下来支持哪些端点/API？

我们一直在寻求扩展此MCP服务器的功能。如果您希望看到支持的特定DataForSEO端点或API，请：

1. 检查 DataForSEO API文档 看看有什么可用的
2. 在我们的GitHub存储库中打开一个问题：

- 您希望看到支持的API/端点； - 用例的简要描述； - 描述您希望实现的任何具体功能。

您的反馈有助于我们确定下一步支持哪些API的优先级！

资源

• 模型上下文协议文档
• DataForSEO API文档