MCP服务器类型脚本

Name: MCP服务器类型脚本
Author: dataforseo

作者：dataforseo125 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

DataForSEO MCP Server

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

功能

AI_OPTIMIZATION API：提供关键词发现、对话优化和实时LLM基准测试的数据；
SERP API：实时搜索结果页面（SERP）数据，包括Google、Bing和Yahoo；
KEYWORDS_DATA API：关键词研究和点击流数据，包括搜索量、每次点击费用和其他指标；
ONPAGE API：允许根据自定义参数爬取网站和网页以获得页面SEO性能指标；
DATAFORSEO LABS API：基于DataForSEO内部数据库和专有算法的关键词、SERP和域名数据；
BACKLINKS API：全面的反向链接分析，包括引用域、锚文本分布和链接质量指标；
BUSINESS DATA API：任何企业实体的公开数据；
DOMAIN ANALYTICS API：网站流量、技术和Whois详情的数据；
CONTENT ANALYSIS API：强大的品牌监控、情感分析和引用管理数据源；

预备条件

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

安装

克隆仓库：

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

安装依赖项：

npm install

设置环境变量：

# 必需
export DATAFORSEO_USERNAME=your_username
export DATAFORSEO_PASSWORD=your_password

# 可选：指定要启用的模块（逗号分隔）
# 如果未设置，则启用所有模块
export ENABLED_MODULES="SERP,KEYWORDS_DATA,ONPAGE,DATAFORSEO_LABS,BACKLINKS,BUSINESS_DATA,DOMAIN_ANALYTICS"

# 可选：指定已启用模块中的哪些提示也启用（提示名称，逗号分隔）
# 如果未设置，则启用已启用模块中的所有提示
export ENABLED_PROMPTS="top_3_google_result_domains,top_5_serp_paid_and_organic"

# 可选：启用完整的API响应
# 如果未设置或设置为false，则服务器会过滤并转换API响应为更简洁的格式
# 如果设置为true，则服务器返回完整的、未经修改的API响应
export DATAFORSEO_FULL_RESPONSE="false"

# 可选：启用简单的过滤器模式
# 如果设置为true，则使用简化版的过滤器模式。
# 这是ChatGPT API或其他无法处理嵌套结构的LLM所必需的。
export DATAFORSEO_SIMPLE_FILTER="false"

作为NPM包安装

你可以全局安装该包：

npm install -g dataforseo-mcp-server

或者在不安装的情况下直接运行：

npx dataforseo-mcp-server

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

# 必需的环境变量
export DATAFORSEO_USERNAME=your_username
export DATAFORSEO_PASSWORD=your_password

# 使用npx运行
npx dataforseo-mcp-server

构建和运行

构建项目：

npm run build

运行服务器：

# 启动本地服务器（直接MCP通信）
npx dataforseo-mcp-server

# 启动HTTP服务器
npx dataforseo-mcp-server http

HTTP服务器配置

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

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

npm run http

认证方法

基本认证
- 发送带有基本认证头的请求：
```
Authorization: Basic <base64-encoded-credentials>
```
- 凭证格式：username:password

环境变量

如果没有提供基本认证，服务器将使用来自环境变量的凭证：

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

Cloudflare Worker部署

DataForSEO MCP服务器可以部署为Cloudflare Worker，以便无服务器地访问DataForSEO API。

Worker特性

边缘分布：在全球范围内通过Cloudflare边缘网络部署
无服务器：无需服务器管理
自动扩展：自动处理流量峰值
MCP协议支持：兼容Streamable HTTP和SSE传输
环境变量：通过Cloudflare仪表板进行安全凭证管理

快速开始

安装Wrangler CLI：
```
npm install -g wrangler
```

配置Worker：

# 登录到Cloudflare
wrangler login

# 设置环境变量
wrangler secret put DATAFORSEO_USERNAME
wrangler secret put DATAFORSEO_PASSWORD

部署Worker：

# 构建并部署
npm run build
wrangler deploy --main build/index-worker.js

配置

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

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

Worker端点

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

POST /mcp：可流式传输的HTTP传输（推荐）
GET /sse：SSE连接建立（已弃用）
POST /messages：SSE消息处理（已弃用）
GET /health：健康检查端点
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": "通过Cloudflare Worker访问DataForSEO API",
  "transport": {
    "type": "http",
    "baseUrl": "https://your-worker.your-subdomain.workers.dev/mcp"
  }
}

可用模块

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

AI_OPTIMIZATION：提供关键词发现、对话优化和实时LLM基准测试的数据；
SERP：实时SERP数据，包括Google、Bing和Yahoo；
KEYWORDS_DATA：关键词研究和点击流数据；
ONPAGE：爬取网站和网页以获得页面SEO性能指标；
DATAFORSEO_LABS：基于DataForSEO数据库和算法的关键词、SERP和域名数据；
BACKLINKS：任何域名、子域名或网页的入站链接、引用域和引用页面的数据；
BUSINESS_DATA：基于Google、Trustpilot和Tripadvisor等平台上公开分享的企业评论和企业信息；
DOMAIN_ANALYTICS：帮助识别用于构建网站的所有可能技术，并提供Whois数据；
CONTENT_ANALYSIS：帮助你发现目标关键词或品牌的引用，并分析其周围的情感；

添加新工具/模块

模块结构

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

AI_OPTIMIZATION：AI优化API
SERP 模块 → SERP API
KEYWORDS_DATA 模块 → 关键词数据API
ONPAGE 模块 → 页面API
DATAFORSEO_LABS 模块 → DataForSEO实验室API
BACKLINKS：模块 → 反向链接API
BUSINESS_DATA：模块 → 企业数据API
DOMAIN_ANALYTICS：模块 → 域名分析API
CONTENT_ANALYSIS：模块 → 内容分析API

实现选项

你可以选择：

在现有模块中添加新的工具
创建全新的模块

添加新工具

这里是如何向任何新或现有的模块添加新工具的方法：

// 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 返回大量字段的数据，这可能会让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);
    }
  }
}

创建新模块

在src/core/modules/下创建新目录用于你的模块：

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

创建模块文件：

// 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),
    };
  }
}

在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'  // 在此处添加你的模块名称
] as const;

在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参数传递配置文件：

# 使用npm
npm run cli -- http --configuration field-config.json

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

# 本地模式
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",
      。
      。
      。
    ],
    ...
  }
}

嵌套字段支持

配置支持使用点符号表示法访问嵌套字段路径：

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

字段发现

要发现任何工具的可用字段：

不带字段配置运行工具以查看完整响应
从API响应中识别你需要的字段
将这些字段路径添加到你的配置文件中

创建自己的配置

复制示例文件：

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

根据需要修改字段选择
使用你的自定义配置：

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

你们希望我们支持哪些端点/API？

我们始终致力于扩展此MCP服务器的能力。如果你有特定的DataForSEO端点或API希望看到支持，请：

查看DataForSEO API文档以了解可用的内容
在我们的GitHub存储库中打开一个问题，包括：
- 你希望看到支持的API/端点；
- 简要描述你的使用场景；
- 描述你希望实现的具体功能。

你的反馈帮助我们优先考虑支持哪些API！