cursor-search-mcp

Standalone MCP server that extracts Cursor's web search into a reusable tool — for any MCP client (pi, Claude Code, Cursor, etc.).

Pure protocol client: talks directly to api2.cursor.sh (RunSSE + BidiAppend, reverse-engineered from cursor-agent). No cursor-agent binary, no child processes, zero npm dependencies.

Features

• 🔍 Web search as a tool — server-side Cursor web search (the same engine behind cursor-agent's web_search), returns summarized answers with source links

• 🔑 API key login — CURSOR_API_KEY (auto token exchange + refresh)

• 🌐 OAuth login — browser-based PKCE device flow, for accounts without API keys

• 🪶 Zero deps — plain Node.js ≥ 18, single-purpose protocol implementation

• 🔒 Token cached with 0600 permissions at ~/.cursor-search-mcp/auth.json

Related MCP server: agent-web-search-mcp

Tools

Install

# from npm (after publish)
npx cursor-search-mcp

# or from source
git clone https://github.com/zzjcool/cursor-search-mcp
cd cursor-search-mcp

Configuration

API key (either way):

export CURSOR_API_KEY=crsr_xxxx
# or
echo "crsr_xxxx" > ~/.cursor-search-mcp/key

Or use OAuth — simplest from the terminal:

npx cursor-search-mcp login     # prints a login URL, waits for you to authorize, caches the token
npx cursor-search-mcp status    # check login state
npx cursor-search-mcp search "mcp spec 2026-07-28 changes"   # one-shot search

Or from inside an agent session: call cursor_oauth_login → open the returned login_url → call cursor_oauth_wait.

On MCP startup without any credentials, the server automatically starts OAuth, prints the login URL to stderr, and polls in the background — the login-aware initialize instructions surface it to the agent.

Optional env vars:

MCP client config (stdio)

{
  "mcpServers": {
    "cursor-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "cursor-search-mcp"],
      "env": { "CURSOR_API_KEY": "crsr_xxxx" }
    }
  }
}

How it works

Reverse-engineered from cursor-agent 2026.10.01 (protocol verified end-to-end):

login    POST /auth/exchange_user_api_key          (API key → accessToken)
         GET  /auth/poll?uuid&verifier             (OAuth PKCE device flow)
search   POST /agent.v1.AgentService/RunSSE        (downstream SSE stream)
         POST /aiserver.v1.BidiService/BidiAppend  (upstream binary frames)

The client maintains the full agent-loop protocol: KV blob get/set ACKs, 5s client heartbeats, web-search approval interactions — so the server-side search engine executes as if invoked from a real agent session.

Caveats

• Uses undocumented Cursor APIs; the protocol may change without notice (pin your version)

• Search quota counts against your Cursor account

• Educational / research purpose — respect Cursor's terms of service

License

MIT

ℹ️ Moved: development continues in search-mcp-hub (packages/cursor-search-mcp). This repo is the v1/v2 history archive. npm publishes continue from the monorepo.