Desearch

Desearch MCP 服务

如果 Desearch 对你有帮助，点个星标可以让更多人发现它。

远程：https://mcp.desearch.ai/mcp，请求头为 Authorization: Bearer <DESEARCH_API_KEY>。

本地：npx -y desearch-mcp-server@latest，环境变量为 DESEARCH_API_KEY。

获取密钥。

在以下平台查找 Desearch

• Official MCP Registry
• Smithery
• Glama
• VoltAgent 官方 MCP 服务
• Gemini CLI 扩展
• Raycast MCP Registry

演示

提示词：搜索网络上的 AI 最新新闻。

web-search 接受 query（必填）和 start（可选分页偏移量：0、10、20，……）。

{
    "name": "web-search",
    "arguments": {
        "query": "latest news on AI"
    }
}

输出示例：

{
    "data": [
        {
            "title": "Example result",
            "link": "https://example.com/page",
            "snippet": "Short preview text."
        }
    ]
}

该工具以美化格式的文本返回上述 JSON：{ "content": [{ "type": "text", "text": "<json above>" }] }。

为 AI Agent 提供 AI 搜索、X 搜索和网络搜索，以及页面提取、X 数据工具和 People Search（在 X、YouTube、LinkedIn 和 TikTok 上查找人物和创作者）。请自备 Desearch API 密钥。

工具

Desearch MCP 服务包含以下工具。

查找工具（包括 search 和 fetch）会设置 readOnlyHint: true、destructiveHint: false 和 openWorldHint: true。people-search 会启动一个付费任务，从用户的 Desearch 余额中扣费，因此 readOnlyHint 为 false，destructiveHint 为 true。people-search-control 可以取消搜索，因此 readOnlyHint 为 false，destructiveHint 为 true。每个工具的 openWorldHint 都为 true，因为调用会访问实时外部来源。

• AI 搜索（ai-search）：执行 AI Twitter 和网页搜索，并返回相关链接和摘要。tools 使用简短的来源 ID（web、twitter、arxiv、wikipedia、hackernews、reddit）。仍接受 Web Search、ArXiv Search、Wikipedia Search、Hacker News Search 和 Reddit Search 等旧标签，并将其作为简短 ID 发送。不接受 youtube。默认值为 ["web", "twitter"]。
• X 搜索（x-search）：搜索 X 上的推文。参数：query（必填）、count（可选，默认值为 20）。排序方式保持为 Top。可选筛选条件：user、start_date、end_date（YYYY-MM-DD）、lang、verified、blue_verified、is_quote、is_video、is_image、min_retweets、min_replies、min_likes。
• 搜索（search）：网页搜索，返回 { results: [{ id, title, url }] }。参数：query（必填）。id 是结果 URL。
• 获取页面（fetch）：以文本形式读取公开页面。参数：id（必填，来自 search 的 http 或 https URL）。
• 网页搜索（web-search）：SERP 样式的网页搜索。参数：query（必填）、start（可选，分页偏移量）。
• 网页链接搜索（web-links-search）：网页链接搜索。参数：prompt（必填）、tools（可选，仅支持 web，默认值为 ["web"]；接受 Web Search 并将其改写为 web）、count（可选，10–200）。links/web API 会拒绝其他来源，因此它们不在枚举值中。
• 提取（extract）：以文本或 HTML 形式读取公开 URL。优先于抓取。参数：url（必填）、format（可选，html 或 text）、js（可选）、wait（可选，毫秒）。
• 网页抓取（web-crawl）：与 extract 使用相同的参数，但走旧版 /web/crawl 路由。SDK 将 webCrawl 标记为弃用，建议改用 extract；保留此工具是为了让该路由仍可访问。新集成请优先使用 extract。
• X 链接搜索（x-links-search）：使用 AI 搜索 X 帖子链接。参数：prompt（必填）、count（可选，10–200）。
• 按 URL 获取 X 帖子（x-posts-by-urls）：获取 URL 列表对应的完整帖子。参数：urls（必填）。
• 按 ID 获取 X 帖子（x-post-by-id）：按 ID 获取一条帖子。参数：id（必填）。
• 按用户获取 X 帖子（x-posts-by-user）：获取某位用户发布的帖子。参数：user（必填）、query（可选）、count（可选，1–100）。
• X 帖子转推者（x-post-retweeters）：获取转推某条帖子的用户。参数：id（必填）、cursor（可选）。
• X 用户帖子（x-user-posts）：获取某位用户的时间线。参数：username（必填）、cursor（可选）。
• X 用户回复（x-user-replies）：获取某位用户发布的帖子和回复。参数：user（必填）、count（可选，1–100）、query（可选）。
• X 帖子回复（x-post-replies）：获取某条帖子的回复。参数：post_id（必填）、count（可选，1–100）、query（可选）。
• X 趋势（x-trends）：获取某个地点的热门话题。参数：woeid（必填）、count（可选，30–100）。
• 人物搜索（people-search）：启动一项付费任务，费用从用户的 Desearch 余额中扣除：根据自然语言描述搜索符合条件的人物。参数：platform（必填：x、youtube、linkedin 或 tiktok）、query（必填，3–1000 个字符）、count（可选，5–200，API 默认值为 25）、min_score（可选，0–100）、exclude（可选，排除的用户名）、metadata（可选标签，见下文）、idempotency_key（可选），以及该平台的筛选条件（见下文）。返回 task_id、状态和 reserved_cost_usd。
• 人物搜索状态（people-search-status）：获取任务的状态、进度和费用，以及截至目前找到的人物分页结果。参数：task_id（必填）、cursor（可选，上一次调用返回的 next_cursor）、limit（可选，1–100，默认值为 25）、include_people（可选，默认值为 true）。免费。
• 控制人物搜索（people-search-control）：暂停、恢复或取消任务。参数：task_id（必填）、action（必填：pause、resume 或 cancel）。免费。
• 列出人物搜索任务（people-search-tasks）：按时间从新到旧列出你的搜索。参数：platform（可选）、status（可选列表，例如 ["running", "paused"]）、limit（可选，1–100）、cursor（可选）、metadata（可选，任务必须包含的标签，最多 3 个，例如 {"campaign": "q4-outbound"}）。免费。
• 列出找到的人物（people-profiles）：列出你的搜索在某个平台上找到的所有人，每人一条记录，并附上找到他们的搜索。参数：platform（必填）、q（可选，在姓名、用户名、简介或地点中搜索文本）、sort（可选：score、recent 或 audience）、limit（可选，1–200，默认值为 25）、cursor（可选），以及筛选条件：has（每个人都必须拥有的渠道：email、website、x、linkedin、instagram、youtube、tiktok）、min_audience、max_audience、min_score、location、verified。免费。 完整的 SDK 方法 → 端点 → MCP 工具映射见 docs/API_MCP_PARITY.md。desearch-js 1.5 的每个公开方法都是一个工具。latestTweets 已从 SDK 中移除（1.0.1 中为 GET /twitter/latest），不会对外提供。desearch-js 1.5 中不包含 People Search；其工具会直接调用 /desearch/people/* 路由，兼容性文档中也列出了这些路由。

People Search

People Search 可根据自然语言描述，查找符合条件的 X 个人资料、YouTube 创作者、LinkedIn 成员或 TikTok 创作者。每个人都会附带匹配度评分、一句话说明匹配原因、受众规模（粉丝数，YouTube 上则为订阅者数）、所在地，以及搜索找到的公开联系方式和链接。

搜索是后台任务：

1. people-search 会启动一个付费任务，从用户的 Desearch 余额中扣费，并立即返回 task_id。这是唯一会产生费用的 People Search 调用。它会按平台的单人价格为 count 位用户预留费用（reserved_cost_usd）。搜索结束后，你只需为实际返回的人数付费（找到任何人时适用每次搜索的最低费用；未找到任何人则免费），剩余预留金额会退还。重试调用时，请发送相同的 idempotency_key，以免启动或支付第二次搜索。
2. 搜索通常需要 1 到 5 分钟。people-search-status 会返回其状态、进度、费用以及目前找到的人。搜索运行期间会陆续返回结果：将 next_cursor 作为 cursor 传回，即可只获取新增结果。当 done 为 true 且 has_more 为 false 时，即表示已获取全部搜索结果。
3. people-search-control 可暂停、恢复或取消搜索。取消的搜索只会对已返回的人收费。

搜索结束后，找到的人员信息会保留 30 天。people-profiles 可跨所有搜索按平台列出这些人员，并支持 has: ["email"] 等筛选条件。

搜索筛选条件取决于平台。不适用的筛选条件会在计费调用前被拒绝。

平台	筛选条件
x	min_followers、max_followers、verified_only、countries、keywords、exclude_keywords
youtube	min_subscribers、max_subscribers、countries、require_contact、keywords、exclude_keywords
linkedin	min_followers、max_followers、countries、keywords、exclude_keywords
tiktok	min_followers、max_followers、require_contact、keywords、exclude_keywords

require_contact 只保留拥有公开电子邮箱的创作者（TikTok 上的邮箱须位于个人简介中）。keywords 和 exclude_keywords 各最多可包含 20 个词。

metadata 可使用自定义键为搜索添加标签，例如 {"campaign": "q4-outbound", "workspace_id": "ws_42"}。每次搜索最多可添加 10 个键；键须为 1–40 个字符，且只能包含 a-z、0-9、_、. 或 -；值须为不超过 200 个字符的字符串。不符合要求的标签会在计费调用前被拒绝。这些标签会作为任务的 metadata 返回；使用 metadata: {"campaign": "q4-outbound"} 调用 people-search-tasks，则只会列出带有这些标签的搜索（最多 3 组键值对，精确匹配）。搜索本身不会使用这些标签。

提示词：查找 10 位拥有公开电子邮箱的 TikTok 护肤创作者。

{
    "name": "people-search",
    "arguments": {
        "platform": "tiktok",
        "query": "Skincare creators who review skincare products",
        "count": 10,
        "require_contact": true
    }
}

输出示例：

{
    "task_id": "3f1c2b9e-8d4a-4c1e-9b7a-2e5f6a7b8c9d",
    "platform": "tiktok",
    "status": "queued",
    "done": false,
    "query": "Skincare creators who review skincare products",
    "count": 10,
    "result_count": 0,
    "reserved_cost_usd": 0.5,
    "created_at": "2026-10-17T10:00:00Z",
    "cost_usd": 0.5,
    "currency": "USD",
    "next": "Searches usually take 1 to 5 minutes. Poll people-search-status with this task_id every 15 to 30 seconds; people appear while it runs."
}

然后在 people-search-status 上使用 {"task_id": "3f1c2b9e-8d4a-4c1e-9b7a-2e5f6a7b8c9d"} 进行轮询：

{
    "task_id": "3f1c2b9e-8d4a-4c1e-9b7a-2e5f6a7b8c9d",
    "platform": "tiktok",
    "status": "running",
    "stage": "processing",
    "done": false,
    "query": "Skincare creators who review skincare products",
    "count": 10,
    "result_count": 4,
    "progress": { "round": 1, "candidates_processed": 40, "qualified": 4 },
    "reserved_cost_usd": 0.5,
    "created_at": "2026-10-17T10:00:00Z",
    "people": [
        {
            "id": "tiktok:example_creator",
            "platform": "tiktok",
            "handle": "example_creator",
            "name": "Example Creator",
            "url": "https://www.tiktok.com/@example_creator",
            "audience": 48200,
            "location": "United States",
            "score": 88,
            "why": "Reviews sunscreens and moisturizers every week.",
            "contacts": [{ "type": "email", "value": "[email protected]" }],
            "links": [{ "type": "instagram", "url": "https://instagram.com/example_creator" }],
            "evidence_url": "https://www.tiktok.com/@example_creator/video/1"
        }
    ],
    "next_cursor": "4",
    "has_more": false,
    "next": "Still searching. Wait 15 to 30 seconds, then call people-search-status again with cursor \"4\" to get only the people found since this call."
}

上面的输出已缩短为仅显示一人。CSV 和 JSON Lines 下载（/export 路由）不是 MCP 工具；如需下载文件，请直接调用 API。

搜索结束后，任务还会说明结束原因和完成情况；每个人也会说明其个人资料中的确认信息（0.3.2 及更高版本）：

{
    "status": "completed",
    "done": true,
    "completion_reason": "cost_limit",
    "coverage_limited": true,
    "warnings": [
        { "code": "partial_enrichment", "platform": "linkedin", "attempted": 20, "failed": 7, "by_reason": { "not_found": 7 } }
    ],
    "people": [
        {
            "handle": "example_engineer",
            "score": 74,
            "fully_verified": false,
            "unverified_criteria": ["Profile fit: Software Engineer based in Georgia (unknown)"],
            "enrichment": "failed",
            "enrichment_error": "not_found"
        }
    ],
    "next": "Finished early: a budget stopped it (cost_limit) before it found 10 people, so more people may match. You have every person it found."
}

• completion_reason 为 count_reached、rounds_exhausted、no_candidates、zero_qualified、candidate_budget、cost_limit、time_limit、cancelled 或 failed 之一。搜索运行期间不会显示此字段。
• 只有当预算导致搜索在找到 count 个人之前停止时，才会显示 coverage_limited（值为 true）。状态仍为 completed。
• warnings 列出导致部分搜索结果可靠性降低的因素。partial_enrichment：搜索后无法读取 attempted 个档案中的 failed 个，因此这些人是根据搜索结果评分的，并显示 enrichment: "failed" 和 enrichment_error。
• 如果每项标准都已通过个人档案或帖子确认，则 fully_verified 为 true。unverified_criteria 最多列出五项未确认的标准：(unknown)、(not met)，或标记为 (applies) 的排除条件。这两项仅供参考：此人仍符合条件。2026-10-20 之前评分的结果不会包含这两项。

前提条件 📋

• Desearch API 密钥
• Node.js（v20.18.1 或更高版本；支持 Node 22。不支持 Node 18。）
• 已安装 Claude Desktop
• Cursor IDE

安装 🛠️

NPM 安装

包名为 desearch-mcp-server。当前版本可在 npm 上查看。发布说明请参阅 CHANGELOG.md。stdio 入口是 desearch-mcp-server bin（build/index.js），需要设置 DESEARCH_API_KEY。

npm install -g desearch-mcp-server

或者无需全局安装即可运行：

npx -y desearch-mcp-server@latest

Cursor 或 Claude 可以直接启动该 bin：

{
    "mcpServers": {
        "desearch": {
            "command": "npx",
            "args": ["-y", "desearch-mcp-server@latest"],
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

全局安装后，command: "desearch-mcp-server"（不带 args）指向同一个入口。

Gemini CLI

从此代码库安装扩展。Gemini CLI 会提示你输入 Desearch API 密钥（以敏感设置的形式存储），并连接到托管服务 https://mcp.desearch.ai/mcp：

gemini extensions install https://github.com/Desearch-ai/mcp-desearch

如需稍后更改密钥，请运行 gemini extensions config desearch。Cline 等 AI Agent 可以按照 llms-install.md 设置服务。

使用 Smithery

通过 Smithery 自动为 Claude Desktop 安装 Desearch MCP 服务：

npx -y @smithery/cli install desearch/desearch --client claude

或者用于 Cursor IDE：

npx -y @smithery/cli install desearch/desearch --client cursor

Windsurf

Windsurf 的 Cascade Agent 会从 mcp_config.json 文件的 mcpServers 键读取 MCP 服务。在 Cascade 面板中打开该文件：点击 ...（Actions）菜单，然后选择 Open MCP config file。Windsurf 版本使用 ~/.codeium/windsurf/mcp_config.json（Windows 上为 %USERPROFILE%\.codeium\windsurf\mcp_config.json）。较新的版本可能会改为打开 ~/.config/devin/mcp_config.json（Windows 上为 %APPDATA%\devin\mcp_config.json）；请编辑该操作打开的文件。

托管服务（无需本地安装）。远程服务使用 serverUrl 和 headers：

{
    "mcpServers": {
        "desearch": {
            "serverUrl": "https://mcp.desearch.ai/mcp",
            "headers": {
                "Authorization": "Bearer your-api-key"
            }
        }
    }
}

如需避免将密钥写入文件，Windsurf 可以插入环境变量："Authorization": "Bearer ${env:DESEARCH_API_KEY}"。

本地 stdio 替代方案：

{
    "mcpServers": {
        "desearch": {
            "command": "npx",
            "args": ["-y", "desearch-mcp-server@latest"],
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

保存文件，然后在 Cascade 中刷新 MCP 服务列表。

Zed

Zed 将 MCP 服务称为上下文服务。使用 zed: open settings file 操作打开设置文件（或依次选择 Settings → AI → MCP Servers → Add Server），然后添加 context_servers 条目。

托管服务：

{
    "context_servers": {
        "desearch": {
            "url": "https://mcp.desearch.ai/mcp",
            "headers": {
                "Authorization": "Bearer your-api-key"
            }
        }
    }
}

本地 stdio 替代方案：

{
    "context_servers": {
        "desearch": {
            "command": "npx",
            "args": ["-y", "desearch-mcp-server@latest"],
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

当 Settings → AI → MCP Servers 中 desearch 旁边的圆点变为绿色（"Server is active"）时，表示服务已就绪。

配置 ⚙️

1. 配置 Cursor IDE 以运行 Desearch MCP 服务

打开 Cursor IDE，使用命令面板快捷键 Cmd+Shift+P 或 Ctrl+Shift+P，然后搜索 Open MCP Settings。点击 Add new global MCP server 打开 mcp.json 文件。

2. 添加 Desearch 服务配置：

{
    "mcpServers": {
        "desearch": {
            "command": "desearch-mcp-server",
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

将 your-api-key 替换为你在 console.desearch.ai/api-keys 获取的实际 Desearch API 密钥。

3. 重启 Cursor IDE

要使更改生效：

1. 完全退出 Cursor IDE
2. 再次启动 Cursor IDE

1. 配置 Claude Desktop 以运行 Desearch MCP 服务

打开 Claude Desktop 应用，并从左上角菜单栏启用 Developer Mode。

启用后，从左上角菜单栏打开 Settings，并导航至 Developer Option，在那里可以找到 Edit Config 按钮。点击该按钮会打开 claude_desktop_config.json 文件，以便进行必要的修改。

或者（如果要从终端打开 claude_desktop_config.json）

对于 macOS：

1. 打开 Claude Desktop 配置文件：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

对于 Windows：

1. 打开 Claude Desktop 配置文件：

code %APPDATA%\Claude\claude_desktop_config.json

2. 添加 Desearch 服务配置：

{
    "mcpServers": {
        "desearch": {
            "command": "desearch-mcp-server",
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

将 your-api-key 替换为你从 console.desearch.ai/api-keys 获取的实际 Desearch API 密钥。

3. 重启 Claude Desktop

要使更改生效：

1. 完全退出 Claude Desktop
2. 再次启动 Claude Desktop
3. 你可以在 Settings > Developer > desearch 中查看状态，以验证服务是否正常运行

远程 Streamable HTTP

同一服务也可以通过 MCP Streamable HTTP 运行，以供远程客户端使用。本地 stdio（desearch-mcp-server、Smithery）不受影响，仍会从环境中读取 DESEARCH_API_KEY。

远程请求不会使用该环境变量。发现服务无需密钥：initialize、notifications/initialized、ping、tools/list、prompts/list、resources/list 和 resources/templates/list 均返回 200，以便市场扫描器读取工具列表。tools/call 和所有其他方法仍需调用方自己的 Desearch API 密钥，也就是从 console.desearch.ai/api-keys 获取的同一密钥：

• Authorization: Bearer <DESEARCH_API_KEY>（首选）
• x-api-key: <DESEARCH_API_KEY>（也接受）
• 完成下方 OAuth 登录后使用 Authorization: Bearer <oauth access token>

也接受直接使用 Authorization: <DESEARCH_API_KEY>。不会从查询字符串读取密钥。没有共享的服务端密钥。受保护的调用如果没有有效密钥或访问令牌，会返回 401，并附带指向 /.well-known/oauth-protected-resource/mcp 的 WWW-Authenticate 标头。托管进程仅在调用需要时，才会将每个请求中的 Desearch API 密钥转发给 Desearch API。OAuth 访问令牌是不透明的：服务端会查找与该令牌关联的密钥，不会将原始密钥放入令牌中。

MCP 端点为 POST /mcp。响应为 JSON（无状态 Streamable HTTP）。对 /mcp 执行 GET 和 DELETE 会返回 405，因为服务端不会保留会话，也不会向客户端推送消息。GET /、GET /health 和 GET /api/health 是无需身份验证的健康检查。

托管端点

公开的 Streamable HTTP 端点为 https://mcp.desearch.ai/mcp。列出工具无需密钥。每次调用 tools/call 时，请通过 Authorization: Bearer <DESEARCH_API_KEY> 发送你的 Desearch API 密钥（首选）。也接受 x-api-key 标头。请使用从 console.desearch.ai/api-keys 获取的密钥。服务端不会从查询字符串读取密钥。远程请求不会使用进程级的 DESEARCH_API_KEY。

Cursor 或任何远程 MCP 客户端：

{
    "mcpServers": {
        "desearch": {
            "url": "https://mcp.desearch.ai/mcp",
            "headers": {
                "Authorization": "Bearer your-api-key"
            }
        }
    }
}

OAuth 登录

遵循 MCP 授权规范（2025-06-18）的客户端可以通过登录来代替每次请求都发送密钥。发现文档包括：

• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-protected-resource/mcp
• GET /.well-known/oauth-authorization-server
• GET /.well-known/openid-configuration（相同的授权服务器文档）

POST /register 用于动态客户端注册。GET /authorize 是供用户粘贴 API 密钥的 Desearch 页面。POST /token 用于交换授权码并轮换刷新令牌。必须使用 PKCE S256。公共客户端的 token_endpoint_auth_method 使用 none。

允许的回调 URL：

• https://claude.ai/api/mcp/auth_callback
• https://claude.com/api/mcp/auth_callback
• https://chatgpt.com/connector_platform_oauth_redirect
• https://chatgpt.com/connector/oauth/{callback_id}
• 任意端口上的环回地址 http://localhost、http://127.0.0.1 和 http://[::1]（主机和路径必须与已注册的回调一致）

连接器 URL 为 https://mcp.desearch.ai/mcp。在登录页面粘贴从 console.desearch.ai/api-keys 获取的密钥。客户端可以自行注册时，请将客户端 ID 留空。

主机的环境变量：

变量	必需	用途
OAUTH_ISSUER	生产环境	不带末尾斜杠的规范源，例如 https://mcp.desearch.ai。当 NODE_ENV=production 或设置了 VERCEL 时必需。若未设置，进程会拒绝 OAuth 和 Bearer 挑战。颁发者绝不会取自 X-Forwarded-Host。在本地，使用请求 URL。
OAUTH_RESOURCE	否	规范 MCP URL。默认为 {OAUTH_ISSUER}/mcp。如果访问令牌中存储的受众与此资源不匹配，则会被拒绝。
OAUTH_STORE	生产环境	memory（本地默认值）或 redis。生产环境（NODE_ENV=production 或 VERCEL）若此值不是 redis，则拒绝启动。
REDIS_URL	当 OAUTH_STORE=redis 时	Redis 连接字符串（redis:// 或 rediss://）。
OAUTH_ENCRYPTION_KEY	当 OAUTH_STORE=redis 时	32 字节密钥，采用 base64 或 hex 编码。使用 openssl rand -base64 32 生成。用于加密存储的 API 密钥。
OAUTH_ACCESS_TTL_SEC	否	访问令牌有效期。默认 3600。范围为 60 至 86400。
OAUTH_REFRESH_TTL_SEC	否	刷新令牌有效期。默认 30 天。范围为 300 秒至 90 天。
OAUTH_CODE_TTL_SEC	否	授权码有效期。默认 300。范围为 30 至 600。
OAUTH_CLIENT_TTL_SEC	否	动态客户端有效期。默认 90 天。范围为 3600 秒至 5 年。
OAUTH_REGISTER_RATE_LIMIT	否	每个 IP 每个时间窗口内的注册尝试次数。默认 10。范围为 1 至 10000。
OAUTH_REGISTER_RATE_WINDOW_SEC	否	注册限流窗口的秒数。默认 3600（1 小时）。范围为 1 至 86400。
OAUTH_AUTHORIZE_RATE_LIMIT	否	每个 IP 每个时间窗口内的登录密钥检查次数。默认 20。范围为 1 至 10000。
OAUTH_AUTHORIZE_RATE_WINDOW_SEC	否	登录密钥检查窗口的秒数。默认 600（10 分钟）。范围为 1 至 86400。
DESEARCH_API_BASE	否	密钥检查主机。默认 https://api.desearch.ai。
OAUTH_REQUIRE_AUTH_ON_INITIALIZE	否	设置为 true，要求在 initialize 时提供密钥或访问令牌。默认关闭，因此不带密钥的 initialize 仍为公开接口。无论如何，tools/list 都是公开接口。

密钥检查会调用 GET /twitter/trends?woeid=1&count=1。真实密钥会通过身份验证，随后因输入无效而被拒绝（HTTP 422），因此此检查不会运行完整的趋势查询。只有 422 才表示密钥有效。401 和 403 会拒绝该密钥。包括 2xx 在内的任何其他状态都属于验证错误，不会被视为有效。

POST /register 对每个 IP 每小时允许 10 次请求。登录密钥检查对每个 IP 每 10 分钟允许 20 次请求。超过限额的请求会返回 429，并附带 Retry-After。在 Vercel 上，地址取自 X-Forwarded-For 的第一个跃点。登录页面使用 Referrer-Policy: same-origin，并在其他授权字段之外提交 response_type=code。表单接受同源的 Origin 或 Referer；当 Origin 缺失或为 null 时，也接受 Sec-Fetch-Site: same-origin。表单会拒绝 Sec-Fetch-Site 为 cross-site 和 same-site、跨源的 Origin，以及没有来源信号的 POST 请求。

与 Claude 一起使用（自定义连接器）

Desearch 目前尚未加入 Claude Connectors Directory。你可以使用 Desearch API 密钥或通过 OAuth 登录，将托管服务添加为自定义连接器。

来源：自定义远程 MCP 连接器 和 连接器身份验证。在 Claude 中，请求标头身份验证是一项测试版功能。

Claude.ai / Claude Desktop（组织管理员）

1. 打开 组织设置 > 连接器。
2. 选择 添加，然后选择 自定义。如果系统询问连接器类型，请选择 Web。
3. 服务 URL：https://mcp.desearch.ai/mcp
4. 登录选项：无需登录。
5. 在 请求标头下，添加 Authorization，并将 Bearer <DESEARCH_API_KEY> 设为其值，将 <DESEARCH_API_KEY> 替换为你的 Desearch API 密钥。
6. 选择 添加。

标头值只需存储一次，组织内所有使用该连接器的人员都可以共用。

OAuth 替代方案：选择登录，而不是请求标头；OAuth 客户端 ID 留空，以便客户端自行注册，然后在 Desearch 页面粘贴 Desearch API 密钥。托管版 Claude 应用的回调 URL 为 https://claude.ai/api/mcp/auth_callback。Claude Code 使用环回回调，此服务接受任意端口。

Claude Code

claude mcp add --transport http desearch https://mcp.desearch.ai/mcp \
  --header "Authorization: Bearer your-api-key"

本地运行

npm install
npm run build
npm run start:http

此服务监听 0.0.0.0:3000（PORT 和 HOST 可覆盖该设置）。MCP_TRANSPORT=http 与 --http 等效。

curl -sS http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer your-api-key' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}'

Cursor（或任何远程 MCP 客户端）：

{
    "mcpServers": {
        "desearch": {
            "url": "http://127.0.0.1:3000/mcp",
            "headers": {
                "Authorization": "Bearer your-api-key"
            }
        }
    }
}

镜像默认使用 stdio MCP（node build/index.js）。Glama 等注册表会启动容器，并通过 stdin/stdout 进行 MCP 通信，因此除非你覆盖设置，否则镜像不会传入 --http。stdio 需要 DESEARCH_API_KEY。Smithery 不使用此镜像命令；smithery.yaml 会启动 node build/index.js 并自行注入 DESEARCH_API_KEY。

Streamable HTTP 是一种覆盖设置。将命令替换为 --http，或者设置 MCP_TRANSPORT=http 并保留默认命令。该模式下镜像仍会公开端口 3000。

docker build -t desearch-mcp .
# stdio (image default)
docker run --rm -e DESEARCH_API_KEY=your-api-key -i desearch-mcp
# Streamable HTTP
docker run --rm -p 3000:3000 desearch-mcp node build/index.js --http
# same HTTP mode via env, without replacing the command
docker run --rm -e MCP_TRANSPORT=http -p 3000:3000 desearch-mcp

在 Vercel 上部署

Vercel 适用于 MCP 处理程序，因为每个 JSON-RPC 调用只需返回一个响应。vercel.json 会构建项目、处理 POST /mcp，并将函数执行时长设为 60 秒。同一文件还会将公开的 OAuth 路径重写为 /api/*。服务接受重写后的路径和公开路径，元数据文档仍会公布公开路径。Hobby 计划对函数执行时长的限制更短，因此 AI Search 工具调用需要使用允许至少 60 秒执行时长的计划。无论使用哪种计划，initialize 和 tools/list 都能快速完成。

OAuth 代码和令牌需要共享存储。在 Vercel 上设置 OAUTH_STORE=redis、REDIS_URL、OAUTH_ENCRYPTION_KEY 和 OAUTH_ISSUER=https://mcp.desearch.ai。如果未设置 OAUTH_ISSUER，或 OAUTH_STORE 不是 redis，服务会拒绝 OAuth，因为 Vercel 会在每个函数中设置 VERCEL。OAUTH_REQUIRE_AUTH_ON_INITIALIZE=true 是可选项。除非客户端会将公开的 initialize 视为跳过登录的理由，否则请不要设置此项。

Vercel 项目无需配置服务端 Desearch API 密钥。部署后，端点为：

https://<project>.vercel.app/mcp

https://mcp.desearch.ai/mcp 是公开主机名。此仓库不会创建 DNS 记录。客户端应发送 Authorization: Bearer <DESEARCH_API_KEY>（推荐）。也接受 x-api-key 标头。

如果你更愿意使用长时间运行的 Node 主机，而不是 Vercel，也可以使用相同的 node build/index.js --http 进程作为备用方案。Docker 镜像默认使用 stdio；传入 --http 或设置 MCP_TRANSPORT=http 即可通过该镜像提供 Streamable HTTP。

故障排除 🔧

常见问题

1. 未找到服务

   • 检查 Claude 或 Cursor Desktop 配置语法
   • 确保已安装 Node.js

2. API 密钥问题

   • 确认你的 DESEARCH_API_KEY 有效
   • 检查 Cursor 或 Claude Desktop 配置中是否正确设置了 DESEARCH_API_KEY
   • 确认 API 密钥前后没有空格
   • 对于远程 HTTP 服务，请发送 Authorization: Bearer <DESEARCH_API_KEY>（推荐）；也接受 x-api-key。这些请求不会使用托管的 DESEARCH_API_KEY 环境变量。

3. 连接问题

   • 完全重启 Claude Desktop 或 Cursor IDE
   • 查看 Claude Desktop 日志：

   # macOS
   tail -n 50 -f ~/Library/Logs/Claude/mcp*.log
   
   # Windows
   type "%APPDATA%\Claude\logs\mcp*.log"