Cursor Mcp Bridge

cursor-mcp-bridge

MCP server that lets any agent or MCP host delegate to the Cursor CLI agent (agent -p) running headless. Cursor is the cheap/fast worker in the fleet — use it for routine work and to map unfamiliar projects without burning your own context.

Mirrors the ergonomics of agy-bridge: every tool takes an optional model and effort, returns a session_id, and supports follow_up. Default model is auto (Cursor picks the cheapest adequate model).

Tools

| Tool | Purpose | |------|---------| | delegate | Run a task on the Cursor agent with full tool access in cwd. | | explore | Read-only exploration. No files → general project map; with files → answer about those files (quotes relevant code inline with file:line). The cheap counterpart to Claude's Explore. | | read_slice | Surgical read-only read: returns ONLY the code relevant to want (exact lines with file:line) from the given files — the full file never enters your context. Use instead of reading large files whole. | | run_filtered | Run a shell command and get back ONLY the lines relevant to want — semantic filtering of huge build/test/log output. | | web_lookup | Web/docs lookup via the Cursor agent's web access. | | follow_up | Continue a prior session by session_id. | | bridge_stats | Report calls and chars returned to context per tool (needs CURSOR_BRIDGE_LOG). |

Every tool accepts: cwd, model (default auto), effort (applied only to parameterized models; auto ignores it).

Requirements

• Node ≥ 18
• Cursor CLI installed as agent and authenticated (agent login).

Install

git clone https://github.com/JaimeJunr/cursor-mcp-bridge.git
cd cursor-mcp-bridge
npm install
npm run build

Register in an MCP host

Claude Code:

claude mcp add cursor-bridge -s user -- node /abs/path/to/cursor-mcp-bridge/dist/index.js

Any host — add to its mcp.json:

{
  "mcpServers": {
    "cursor-bridge": {
      "command": "node",
      "args": ["/abs/path/to/cursor-mcp-bridge/dist/index.js"]
    }
  }
}

Configuration (env)

| Var | Default | Meaning | |-----|---------|---------| | CURSOR_BIN | agent | Path to the Cursor CLI binary. | | CURSOR_BRIDGE_MODEL | auto | Default model when a call omits model. | | CURSOR_BRIDGE_FORCE | (off) | If 1/true, pass --force so commands run without prompts. | | CURSOR_BRIDGE_TIMEOUT_MS | 600000 | Per-call timeout. | | CURSOR_BRIDGE_LOG | (off) | Path to a JSONL file; when set, every call logs {tool, outChars} for bridge_stats. | | CURSOR_BRIDGE_HOOK_MIN_LINES | 300 | Line threshold above which the optional hook (below) nudges toward read_slice. | | CURSOR_BRIDGE_AGENT_DELAY_MS | 350 | Delay before the Agent\|Task injection emits, to win the last-wins race vs context-mode. 0 disables. | | CONTEXT_MODE_ROUTING | (marketplace path) | Override path to context-mode's routing.mjs (imported to preserve its block in subagents). |

> Security: delegate and run_filtered can run shell autonomously (with CURSOR_BRIDGE_FORCE). > explore, read_slice and web_lookup run in read-only modes (plan / ask).

Make the agent actually use it

Registering the tools is not enough. Two structural forces push the agent back to native tools: (1) the host rule "prefer the dedicated file/search tools", and (2) these MCP tools are usually deferred — the agent must run a tool-search to even load their schemas, so the always-loaded Read/Grep/WebSearch win by default. Three fixes, strongest first:

1. Call-time hook (recommended). A PreToolUse hook that nudges the agent toward the bridge at the moment it reaches for a native tool — text in a config file loses under pressure, a call-time reminder does not. This repo ships one at [hooks/prefer-cursor-bridge.mjs](hooks/prefer-cursor-bridge.mjs): it is non-blocking, runs on node (already required), and only fires where it pays. Wire it into your host's settings (Claude Code settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Grep|Glob|WebSearch|WebFetch",
        "hooks": [
          { "type": "command", "command": "node /abs/path/to/cursor-mcp-bridge/hooks/prefer-cursor-bridge.mjs", "timeout": 5 }
        ]
      }
    ]
  }
}

What it emits, and when — each fires at most once per session (deduplicated in a tmp file keyed by session_id), because a repeated nudge is worse than none: the agent learns to ignore it and every fire costs tokens.

> - Read over CURSOR_BRIDGE_HOOK_MIN_LINES lines → suggests read_slice (once per file). > - WebSearch/WebFetch → suggests web_lookup (once). > - Grep/Glob → emits the one-time preload reminder to run the ToolSearch for the > deferred bridge tools. This is why Grep/Glob can sit in the matcher without the old > constant-noise cost — the dedup collapses them to a single fire. > - The first qualifying nudge of the session (whichever tool triggers it) also carries > that preload reminder, so the schemas get loaded even in a Read-only or web-only session.

To reset the dedup and see the nudges again, start a new session (or delete cursor-bridge-nudged-.json from your OS temp dir — os.tmpdir(), e.g. /tmp on Linux, not necessarily $TMPDIR).

Reaching subagents too (Agent|Task matcher)

The nudges above only steer the main loop. Spawned subagents never see them — and if you also run the context-mode plugin, its own Agent|Task hook appends a strong "route everything through context-mode" block to each subagent prompt that never mentions the bridge, so subagents are born blind to it. Wire this hook for Agent|Task as well to fix that:

{ "matcher": "Agent|Task",
  "hooks": [{ "type": "command", "command": "node /abs/path/to/cursor-mcp-bridge/hooks/prefer-cursor-bridge.mjs", "timeout": 10 }] }

On an Agent/Task call the hook appends a compact cursor-bridge preference (plus the ToolSearch preload line) to the subagent's prompt via updatedInput.

> Coexisting with context-mode. Multiple PreToolUse hooks returning > updatedInput for one tool do not merge — it's last-to-finish-wins, > non-deterministic. To never clobber context-mode's block, this hook imports > context-mode's live routing, takes the prompt it would produce (already > carrying its block), and appends the bridge preference to it. So whoever wins > the race, context-mode's block survives; the bridge preference lands whenever > this hook wins — which CURSOR_BRIDGE_AGENT_DELAY_MS (default 350ms) > biases toward by finishing after context-mode's heavier hook. If context-mode's > routing can't be imported the hook injects nothing (preserving context-mode > is the invariant). Set CONTEXT_MODE_ROUTING to point at a non-default path, > or CURSOR_BRIDGE_AGENT_DELAY_MS=0 to disable the delay.

2. Preload the deferred tools. Tell the agent to load the schemas once per session so they are "in hand". Add to your CLAUDE.md/AGENTS.md:

At the start of any session involving code reading/exploration, run tool-search once for
`read_slice, explore, run_filtered, web_lookup` so their schemas are loaded — otherwise the
deferred tools lose to the always-loaded native Read/Grep by default.

3. Reconcile the conflict in CLAUDE.md. State the precedence explicitly:

The host rule "prefer dedicated file/search tools" applies to the EDIT path (Edit needs the
file content → native Read). For PURE reading/locating/web (no edit), cursor-bridge takes
precedence over native Read/Grep/Glob/WebSearch/WebFetch. Read a large file whole with native
Read ONLY when you are about to edit it.

Develop

npm test       # vitest — unit tests for model resolution / arg building
npm run dev    # run from source via tsx

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JaimeJunr
• Source: JaimeJunr/cursor-mcp-bridge
• License: MIT

Install and usage instructions live in the source repository linked above.