DataForSEO MCP 服务器

DataForSEO 的 Model Context Protocol (MCP) 服务器实现，使 Claude 能够通过标准化接口与选定的 DataForSEO API 交互并获取 SEO 数据。

功能

• SERP API：提供 Google、Bing 和 Yahoo 的实时搜索引擎结果页面 (SERP) 数据；
• KEYWORDS_DATA API：关键词研究和点击流数据，包括搜索量、每次点击成本等指标；
• ONPAGE API：允许根据自定义参数爬取网站和网页以获取页面 SEO 性能指标；
• DATAFORSEO_LABS API：基于 DataForSEO 内部数据库和专有算法的关键词、SERP 和域名数据。

前提条件

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

安装

1. 克隆仓库：
   bash
   git clone https://github.com/dataforseo/mcp-server-typescript
   cd mcp-server-typescript

2. 安装依赖项：
   bash
   npm install

3. 设置环境变量：
   bash

   必需

   export DATAFORSEO_USERNAME=your_username
   export DATAFORSEO_PASSWORD=your_password

   可选：指定启用哪些模块（逗号分隔）

   如果未设置，则所有模块都将被启用

   export ENABLED_MODULES="SERP,KEYWORDS_DATA,ONPAGE,DATAFORSEO_LABS,BACKLINKS,BUSINESS_DATA,DOMAIN_ANALYTICS"

   可选：启用完整的 API 响应

   如果未设置或设置为 false，服务器将过滤并转换 API 响应为更简洁的格式

   如果设置为 true，服务器将返回完整且未经修改的 API 响应

   export DATAFORSEO_FULL_RESPONSE="false"

作为 NPM 包安装

您可以全局安装该包：

bash
npm install -g dataforseo-mcp-server

或者直接运行而无需安装：

bash
npx dataforseo-mcp-server

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

bash

必需的环境变量

export DATAFORSEO_USERNAME=your_username
export DATAFORSEO_PASSWORD=your_password

使用 npx 运行

npx dataforseo-mcp-server

构建和运行

构建项目：
bash
npm run build

运行服务器：
bash

启动本地服务器（直接 MCP 通信）

npx dataforseo-mcp-server

启动 HTTP 服务器

npx dataforseo-mcp-server http

HTTP 服务器配置

服务器默认运行在端口 3000 上，并支持基本认证和基于环境变量的认证。

要启动 HTTP 服务器，请运行：
bash
npm run http

认证方法

1. 基本认证

   • 发送带有 Basic Auth 头的请求：

     Authorization: Basic

   • 凭证格式：username:password

2. 环境变量

   • 如果没有提供基本认证，服务器将使用环境变量中的凭证：
     bash
     export DATAFORSEO_USERNAME=your_username
     export DATAFORSEO_PASSWORD=your_password

可用模块

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

• SERP：Google、Bing 和 Yahoo 的实时 SERP 数据；
• KEYWORDS_DATA：关键词研究和点击流数据；
• ONPAGE：爬取网站和网页以获取页面 SEO 性能指标；
• DATAFORSEO_LABS：基于 DataForSEO 数据库和算法的关键词、SERP 和域名数据；
• BACKLINKS：任何域名、子域名或网页的入站链接、引用域和引用页面的数据；
• BUSINESS_DATA：基于 Google、Trustpilot 和 Tripadvisor 等平台上公开分享的商业评论和商业信息；
• DOMAIN_ANALYTICS：帮助识别用于构建网站的所有可能技术，并提供 Whois 数据；

添加新工具/模块

模块结构

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

• SERP 模块 → SERP API
• KEYWORDS_DATA 模块 → Keywords Data API- ONPAGE 模块 → OnPage API
• DATAFORSEO_LABS 模块 → DataForSEO Labs API
• BACKLINKS 模块 → Backlinks API
• BUSINESS_DATA 模块 → Business Data API
• DOMAIN_ANALYTICS 模块 → Domain Analytics API

实现选项

你可以选择：

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

添加新工具

以下是如何向任何新的或现有的模块中添加新工具：

typescript
// src/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 返回的数据非常详尽，包含许多字段，这可能会让AI代理处理起来感到不知所措。
// 我们只选择最相关的字段以确保响应高效且集中。
this.fields = [
title , // 示例：包含标题字段
description , // 示例：包含描述字段
url , // 示例：包含URL字段
// 根据需要添加更多字段
];
}

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

getDescription() {
return 工具的功能描述 ;
}

getParams(): z.ZodRawShape {
return {
// 必需参数
keyword: z.string().describe( 要搜索的关键字 ),
location: z.string().describe( 位置格式为"城市,地区,国家"或仅"国家" ),

  // 可选参数
  fields: z.array(z.string()).optional().describe( 响应中返回的具体字段。如果未指定，则返回所有字段 ),
  language: z.string().optional().describe( 语言代码（例如："en"） ),
};

}

async handle(params: any) {
try {
// 发起API调用
const response = await this.client.makeRequest({
endpoint: /v3/dataforseo_endpoint_path ,
method: POST ,
body: [{
// 你的请求参数
keyword: params.keyword,
location: params.location,
language: params.language,
}],
});

  // 验证响应中的错误
  this.validateResponse(response);

  // 如果主要数据数组在tasks[0].result[:]字段中指定
  const result = this.handleDirectResult(response);
  // 如果主要数据数组在tasks[0].result[0].items字段中指定
  const result = this.handleItemsResult(response);
  // 格式化并返回响应
  return this.formatResponse(result);
} catch (error) {
  // 处理并格式化任何错误
  return this.formatErrorResponse(error);
}

}
}

创建新模块

1. 在src/modules/下为你的模块创建一个新的目录：
   bash
   mkdir -p src/modules/your-module-name

2. 创建模块文件：
   typescript
   // src/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/config/modules.config.ts中注册你的模块：
   typescript
   export const AVAILABLE_MODULES = [
   SERP ,
   KEYWORDS_DATA ,
   ONPAGE ,
   DATAFORSEO_LABS ,
   YOUR_MODULE_NAME // 在这里添加你的模块名称
   ] as const;

2. 在src/index.ts中初始化你的模块：
   typescript
   if (isModuleEnabled( YOUR_MODULE_NAME , enabledModules)) {
   modules.push(new YourModuleNameModule(dataForSEOClient));
   }## 您希望我们接下来支持哪些端点/API？

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

1. 查看DataForSEO API文档以了解可用内容
2. 在我们的GitHub仓库中提出一个issue，包含以下信息：
   • 您希望支持的API/端点；
   • 您使用场景的简要描述；
   • 描述您希望实现的任何特定功能。

您的反馈将帮助我们确定接下来优先支持哪些API！

资源

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