This project implements a fully-functioning, local OpenAI-compatible LLM server that acts as a bridge to the Cursor Python SDK (cursor-sdk). It enables you to use Cursor's powerful local agent (the same agent that runs inside the Cursor IDE) with any standard OpenAI API client (such as OpenCode).
Additionally, it provides a standalone Model Context Protocol (MCP) server that exposes a tool to execute Cursor Agent tasks programmatically.
- OpenAI Compatibility: Serves
/v1/chat/completionssupporting both streaming (stream=True) and non-streaming modes. - First-Class Reasoning/Thinking Support: Streams reasoning via
reasoning_contentand answer text viacontent, ordered using the Cursor SDK’s canonicalthinkingMessage/assistantMessageconversation steps (with token deltas only as a fallback). Supports interleaved think→answer→think→answer turns and inserts a freshrole: assistantchunk between segments so OpenCode does not merge separate answer blocks. - Stateful Conversation Resumption: Integrates message-prefix matching and custom session tracking to automatically resume local Cursor Agents (
Agent.resume()) for multi-turn chats. - Tool Call Interception Bridge: Seamlessly translates OpenAI tool definitions (
toolsparameters) into dynamic MCP tool listings for the Cursor Agent. It intercepts agent tool call invocations, suspends the execution loop, yields the tool calls to the client, and resumes the agent upon receiving results. - Custom Workspace Pathing: Dynamically matches host workspaces via environment variable (
CURSOR_WORKSPACE), content block extraction, or custom HTTP request header (X-Workspace-Path). - Standalone MCP Server: Exposes a
run_cursor_agenttool usingFastMCPfor programmatically spawning local workspace tasks.
- Make sure you have Python (3.10+) installed.
- Copy the environment template file:
cp .env.template .env
- Install the dependencies:
pip install -r requirements.txt
- Open
.envand set yourCURSOR_API_KEY(retrieve it from the Cursor Dashboard -> Integrations). - Configure optional parameters like the default
PORT(defaults to8764) andCURSOR_WORKSPACE(the workspace root directory you want the agent to edit/read).
Start the bridge server in your terminal:
python3 cursor_bridge_server.pyOr using uv (which automatically installs the required Python version and dependencies defined in pyproject.toml):
uv run cursor_bridge_server.pyBy default, the server runs on http://127.0.0.1:8764.
To allow other devices on your local network to connect to this server:
- Open
.envand changeHOST=127.0.0.1toHOST=0.0.0.0. - Restart the server:
python3 cursor_bridge_server.py. - Find your local IP address (e.g., run
ipconfig getifaddr en0on macOS). - Configure your client application with your computer's local IP (e.g.,
"baseURL": "http://192.168.1.50:8764/v1").
To use this bridge in your editor as a backend proxy, add the following configuration block:
{
"cursor": {
"npm": "@ai-sdk/openai-compatible",
"name": "Cursor Backend Proxy",
"options": {
"baseURL": "http://127.0.0.1:8764/v1",
"apiKey": "dummy-key-not-used-by-proxy"
},
"models": {
"composer-2.5": {
"name": "Composer 2.5 fast",
"limit": {
"context": 200000,
"output": 65536
}
},
"composer-2.5-slow": {
"name": "Composer 2.5 slow",
"limit": {
"context": 200000,
"output": 65536
}
}
}
}
}X-Workspace-Path: Specify the absolute local folder path that the Cursor Agent should operate in. If not sent, the server defaults to theCURSOR_WORKSPACEenv variable or the directory where the server was launched.X-Session-ID: Manually specify a session ID to keep conversation state across requests. If omitted, the server will fall back to using theuserfield or automatically prefix-matching message histories.
If you are using a terminal-native client like OpenCode that connects directly to MCP servers:
python3 mcp_server.pyOr using uv:
uv run mcp_server.pyThis starts an MCP stdio server. You can configure OpenCode or Claude Desktop to start this server by configuring the command:
"mcpServers": {
"cursor-bridge": {
"command": "uv",
"args": ["run", "/absolute/path/to/mcp_server.py"],
"env": {
"CURSOR_API_KEY": "your_api_key_here",
"CURSOR_WORKSPACE": "/path/to/your/workspace"
}
}
}run_cursor_agent(prompt: str, cwd: str = None) -> str: Instructs the local Cursor Agent to run the task described inpromptinside the workspacecwdand returns the final text response.
A mock-integration test suite is included to verify the complete server flow (including tool calling and SSE queue pipes) without requiring an internet connection or a real API key.
Run the tests:
python3 test_server.pyYou can also run manual HTTP requests against a running server.
curl http://127.0.0.1:8764/v1/modelscurl http://127.0.0.1:8764/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "composer-2.5-slow",
"messages": [{"role": "user", "content": "Say hello!"}],
"stream": false
}'curl http://127.0.0.1:8764/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "composer-2.5-slow",
"messages": [{"role": "user", "content": "Explain what Python is in one sentence."}],
"stream": true
}'