Desearch

io.github.Desearch-aiv0.1.2更新于 Oct 1, 2026

AI search, X search, web search, page extraction, and X trends.

已验证Streamable HTTP可网页运行Web Search & ScrapingCommunication & Collaboration

概览

AI 生成的概览

让助手通过 Desearch 进行实时 AI、X（Twitter）和网页搜索，提取网页内容，并读取 X 趋势和帖子。

功能
该服务器把 Desearch 的搜索与社交数据 API 封装为 MCP 工具。工具包括 ai-search（网页与 Twitter 综合搜索，返回摘要和链接）、x-search、web-search、web-links-search、用于把公开网址读取为文本或 HTML 的 extract，以及旧版 web-crawl 路由。其他工具可按网址、ID 或用户获取 X 帖子，获取转发者、用户时间线和回复、帖子回复，以及按 WOEID 查询热门话题。
适用场景
适合助手需要最新网页或 X 内容而非训练数据的场景：调研与摘要、监控趋势或账号、抓取推文串与回复，或获取网页正文以便进一步分析。
运行要求
需要来自 Desearch 控制台的 API 密钥。本地 stdio 方式需要 Node.js 20.18.1 或更高版本（不支持 Node 18）以及 npm 包 desearch-mcp-server，密钥放在 DESEARCH_API_KEY 中。托管端点 mcp.desearch.ai/mcp 无需本地安装，每次请求通过 x-api-key 请求头或 Authorization bearer 值携带密钥。需要网络访问。
安装前请注意
Desearch API 密钥属于机密，费用计入你的 Desearch 账户；README 指出 AI Search 调用可能耗时约 30 秒，在函数时限较短的托管平台上需注意。在托管端点上，密钥会随每次请求转发给 Desearch API；在 Claude 组织连接器中，请求头的值只保存一次，并由使用该连接器的所有成员共享。查询内容和抓取的网址会发送到 Desearch 的服务。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Desearch，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable，通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "mcpServers": {
    "mcp-desearch": {
      "type": "http",
      "url": "https://mcp.desearch.ai/mcp"
    }
  }
}

README

Desearch MCP Server

[npm version]

A Model Context Protocol (MCP) server lets clients like Claude or Cursor use Desearch for real-time AI search, X search, web search, page extraction, and X trends.

Tools

The Desearch MCP server includes the following tools:

  • AI Search (ai-search): Performs real-time AI Twitter and web searches with relevant links and summary. tools uses short source ids (web, twitter, arxiv, wikipedia, youtube, hackernews, reddit). Older labels such as Web Search are still accepted and sent to the API as the short id. Default is ["web", "twitter"].
  • X Search (x-search): Real-time tweet search on X. Arguments: query (required), count (optional, default 20). Sort stays Top. Optional filters: user, start_date, end_date (YYYY-MM-DD), lang, verified, blue_verified, is_quote, is_video, is_image, min_retweets, min_replies, min_likes.
  • Web Search (web-search): SERP-style web search. Arguments: query (required), start (optional pagination offset).
  • Web Links Search (web-links-search): Web link search. Arguments: prompt (required), tools (optional, only web, default ["web"]; Web Search is accepted and rewritten to web), count (optional, 10–200). The links/web API rejects other sources, so they are not in the enum.
  • Extract (extract): Read a public URL as text or HTML. Preferred over crawl. Arguments: url (required), format (optional, html or text), js (optional), wait (optional milliseconds).
  • Web Crawl (web-crawl): Same arguments as extract, on the legacy /web/crawl route. The SDK marks webCrawl deprecated in favor of extract; this tool stays so that route remains reachable. Prefer extract for new integrations.
  • X Links Search (x-links-search): AI search for X post links. Arguments: prompt (required), count (optional, 10–200).
  • X Posts By URLs (x-posts-by-urls): Full posts for a list of URLs. Argument: urls (required).
  • X Post By ID (x-post-by-id): One post by ID. Argument: id (required).
  • X Posts By User (x-posts-by-user): Posts by a user. Arguments: user (required), query (optional), count (optional, 1–100).
  • X Post Retweeters (x-post-retweeters): Users who retweeted a post. Arguments: id (required), cursor (optional).
  • X User Posts (x-user-posts): A user's timeline. Arguments: username (required), cursor (optional).
  • X User Replies (x-user-replies): Posts and replies by a user. Arguments: user (required), count (optional, 1–100), query (optional).
  • X Post Replies (x-post-replies): Replies to a post. Arguments: post_id (required), count (optional, 1–100), query (optional).
  • X Trends (x-trends): Trending topics for a location. Arguments: woeid (required), count (optional, 30–100).

The full SDK method → endpoint → MCP tool map is in docs/API_MCP_PARITY.md. Every public desearch-js 1.5 method is a tool. latestTweets was removed from the SDK (GET /twitter/latest in 1.0.1) and is not exposed.

Prerequisites 📋

Installation 🛠️

NPM Installation

The package name is desearch-mcp-server. The first npm publish of this tree is 0.1.2 (the registry still has 0.0.1). See CHANGELOG.md for the 0.0.1 → 0.1.2 migration. The stdio entry is the desearch-mcp-server bin (build/index.js), which requires DESEARCH_API_KEY.

bash
npm install -g desearch-mcp-server

Or run it without a global install:

bash
npx -y desearch-mcp-server

Cursor or Claude can start that bin directly:

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

command: "desearch-mcp-server" (no args) is the same entry after the global install above.

Using Smithery

To install the Desearch MCP server for Claude Desktop automatically via Smithery:

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

Or for Cursor IDE:

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

Windsurf

Windsurf's Cascade agent reads MCP servers from mcp_config.json under the mcpServers key. Open it from the Cascade panel: click the ... (Actions) menu, then Open MCP config file. Windsurf builds use ~/.codeium/windsurf/mcp_config.json (on Windows, %USERPROFILE%\.codeium\windsurf\mcp_config.json). Newer builds may open ~/.config/devin/mcp_config.json instead (Windows: %APPDATA%\devin\mcp_config.json); edit whichever file that action opens.

Hosted server (no local install). Remote servers use serverUrl with headers:

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

To keep the key out of the file, Windsurf can interpolate an environment variable: "x-api-key": "${env:DESEARCH_API_KEY}".

Local stdio alternative:

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

Save the file, then refresh the MCP servers list in Cascade.

Zed

Zed calls MCP servers context servers. Open your settings file with the zed: open settings file action (or use Settings → AI → MCP Servers → Add Server) and add a context_servers entry.

Hosted server:

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

Local stdio alternative:

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

The server is ready when the dot next to desearch in Settings → AI → MCP Servers turns green ("Server is active").

Configuration ⚙️

1. Configure Cursor IDE to run the Desearch MCP server

Open Cursor IDE, access command palette Cmd+Shift+P or Ctrl+Shift+P, and search for Open MCP Settings. Click on Add new global MCP server to open the mcp.json file.

2. Add the Desearch server configuration:

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

Replace your-api-key with your actual Desearch API key from console.desearch.ai/api-keys.

3. Restart Cursor IDE

For the changes to take effect:

  1. Completely quit Cursor IDE
  2. Start Cursor IDE again

1. Configure Claude Desktop to run the Desearch MCP server

Open the Claude Desktop app and enable Developer Mode from the top-left menu bar.

Once enabled, open Settings (also from the top-left menu bar) and navigate to the Developer Option, where you'll find the Edit Config button. Clicking it will open the claude_desktop_config.json file, allowing you to make the necessary edits.

OR (if you want to open claude_desktop_config.json from terminal)

For macOS:
  1. Open your Claude Desktop config:
bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
For Windows:
  1. Open your Claude Desktop configuration:
powershell
code %APPDATA%\Claude\claude_desktop_config.json

2. Add the Desearch server configuration:

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

Replace your-api-key with your actual Desearch API key from console.desearch.ai/api-keys.

3. Restart Claude Desktop

For the changes to take effect:

  1. Completely quit Claude Desktop
  2. Start Claude Desktop again
  3. You can verify the server by checking status in Settings > Developer > desearch

Remote Streamable HTTP

The same server can run over MCP Streamable HTTP for a remote client. Local stdio (desearch-mcp-server, Smithery) is unchanged and still reads DESEARCH_API_KEY from the environment.

Remote requests do not use that environment variable. Each request must carry the caller's own Desearch API key, the same key from console.desearch.ai/api-keys:

  • Authorization: Bearer <DESEARCH_API_KEY> (preferred)
  • x-api-key: <DESEARCH_API_KEY>

A bare Authorization: <DESEARCH_API_KEY> value is also accepted. The key is not read from the query string. There is no shared server secret: the hosted process forwards the per-request key to the Desearch API.

The MCP endpoint is POST /mcp. Responses are JSON (stateless Streamable HTTP). GET and DELETE on /mcp return 405 because the server does not keep a session or push server-to-client messages. GET / and GET /health are unauthenticated health checks.

Hosted endpoint

The public Streamable HTTP endpoint is https://mcp.desearch.ai/mcp. Send your Desearch API key on each request in the x-api-key header. Authorization: Bearer <key> is also accepted. Use the key from console.desearch.ai/api-keys. The server does not read a key from the query string. Remote requests do not use a process-level DESEARCH_API_KEY.

Cursor, or any remote MCP client:

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

Use with Claude (custom connector)

Desearch is not in the Claude Connectors Directory yet. You can add the hosted server as a custom connector with your Desearch API key.

Sources: Custom remote MCP connectors and connector authentication. Request-header authentication is a beta feature in Claude.

Claude.ai / Claude Desktop (organization admin)

  1. Open Organization settings > Connectors.
  2. Select Add, then Custom. If asked for the connector type, choose Web.
  3. Server URL: https://mcp.desearch.ai/mcp
  4. Sign-in option: No sign-in.
  5. Under Request headers, add x-api-key with your Desearch API key as the value.
  6. Select Add.

The header value is stored once and shared by everyone in the organization who uses the connector.

Claude Code

bash
claude mcp add --transport http desearch https://mcp.desearch.ai/mcp \  --header "x-api-key: YOUR_DESEARCH_API_KEY"

Run locally

bash
npm installnpm run buildnpm run start:http

This listens on 0.0.0.0:3000 (PORT and HOST override that). MCP_TRANSPORT=http is the same as --http.

bash
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 (or any remote MCP client):

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

The image default is stdio MCP (node build/index.js). Registries such as Glama start the container and speak MCP on stdin/stdout, so the image does not pass --http unless you override it. Stdio requires DESEARCH_API_KEY. Smithery does not use this image command; smithery.yaml starts node build/index.js and injects DESEARCH_API_KEY itself.

Streamable HTTP is an override. Replace the command with --http, or set MCP_TRANSPORT=http and keep the default command. The image still exposes port 3000 for that mode.

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

Deploy on Vercel

Vercel fits this server because the handler is stateless and answers each JSON-RPC call in one response. vercel.json builds the project, serves POST /mcp, and allows tool calls up to 60 seconds (Orbit searches run about 30 seconds). Hobby plans cap function duration lower than that, so AI Search tool calls need a plan that allows at least 60 seconds. initialize and tools/list are short either way.

No server-side Desearch API key is required in the Vercel project. After deploy, the endpoint is:

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

https://mcp.desearch.ai/mcp is the public hostname. This repo does not create DNS records. Clients send x-api-key, or Authorization: Bearer <key>.

The same node build/index.js --http process is the fallback if you would rather run a long-lived Node host instead of Vercel. The Docker image defaults to stdio; pass --http or set MCP_TRANSPORT=http to serve Streamable HTTP from it.

Troubleshooting 🔧

Common Issues

  1. Server Not Found

    • Check Claude or Cursor Desktop configuration syntax
    • Ensure Node.js is installed

  2. API Key Issues

    • Confirm your DESEARCH_API_KEY is valid
    • Check the DESEARCH_API_KEY is correctly set in the Cursor or Claude Desktop config
    • Verify that there are no spaces around the API key
    • For the remote HTTP server, send Authorization: Bearer <key> or x-api-key. A hosted DESEARCH_API_KEY environment variable is not used for those requests.

  3. Connection Issues

    • Restart Claude Desktop or Cursor IDE completely
    • Check Claude Desktop logs:
    bash
    # macOStail -n 50 -f ~/Library/Logs/Claude/mcp*.log
# Windowstype "%APPDATA%\Claude\logs\mcp*.log"

来源：README.md，提交 5452f7f

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v0.1.2最新Oct 1, 2026