GrokBot ↔ Cursor Agent Bridge

A self-hosted MCP gateway and Agent Plugin template that lets Grok Bot talk to your local Cursor Agent CLI (agent / cursor-agent). Grok Bot remains the chat interface; Cursor Agent runs on your machine and produces the answer.

Pattern and security model inspired by iamsupersocks/grokbot-hermes-bridge: exactly two MCP tools, OAuth + PKCE, localhost bind, fail-closed startup.

The repository is operator-agnostic: it contains no live endpoint, token, hostname, private address, user path, account handle, or conversation.

Quick start

Linux or macOS, in one auditable command:

git clone https://github.com/kdriedger/grokbot-cursor-bridge.git && cd grokbot-cursor-bridge && ./scripts/install.sh

Already cloned:

./scripts/install.sh
python3 scripts/doctor.py

The installer is local and auditable. It does not download a remote shell, does not use sudo, does not start the gateway, and does not write a real public hostname unless you pass one. Non-interactive and dry-run modes are available for review and tests:

./scripts/install.sh --dry-run --non-interactive
./scripts/install.sh --non-interactive --endpoint https://mcp.example.com/mcp

Then fill the remaining local paths in .env.local (mode 600, never commit it). The owner code is generated on disk; do not paste it into chat. See docs/TUTORIAL.md for the illustrated walkthrough. Doctor deliberately stays red while the example hostname or agent paths are still placeholders.

Related MCP server: xAI Grok MCP Bridge

How it works

1. The gateway runs beside your Cursor Agent CLI and exposes exactly two MCP tools: cursor_ask and cursor_status.

2. An HTTPS reverse proxy or tunnel makes /mcp reachable from Grok Bot.

3. Grok Bot discovers the gateway's OAuth flow. You approve the connection in a browser with a private owner code stored only in the server environment.

4. The plugin sends user requests to agent --print and returns the bounded reply.

There is no SSH endpoint, generic shell tool, environment dump, or committed credential. The owner code is not accepted as an MCP bearer token.

Requirements

• Python 3.11+

• A working Cursor Agent CLI (agent or cursor-agent) on the gateway machine

• A workspace directory the agent is allowed to operate on

• A Cursor API key (CURSOR_API_KEY / CURSOR_BRIDGE_API_KEY) or an existing agent login session on that machine

• A public HTTPS hostname or tunnel that forwards to 127.0.0.1:8099

• Grok Bot, Codex, Cursor, or another Streamable HTTP MCP client with OAuth

Run the gateway

After the installer (or the equivalent local venv + .env.local setup):

. .venv/bin/activate
set -a
. ./.env.local
set +a
python -m cursor_gateway.mcp --host 127.0.0.1 --port 8099

At minimum .env.local must contain:

CURSOR_BRIDGE_SECRET=<64-random-hex-characters>
CURSOR_BRIDGE_PUBLIC_BASE_URL=https://mcp.example.com
CURSOR_BRIDGE_ALLOWED_HOSTS=localhost,127.0.0.1,mcp.example.com
CURSOR_BRIDGE_AGENT_BIN=/absolute/path/to/agent
CURSOR_BRIDGE_WORKSPACE=/absolute/path/to/workspace
CURSOR_BRIDGE_API_KEY=<cursor-api-key>

GET /health should return {"status":"ok"}. Put HTTPS in front of the service; do not expose port 8099 directly. See deploy/ for generic examples.

Configure the plugin

The installer calls scripts/configure_plugin.py for you. To repeat it:

python scripts/configure_plugin.py https://mcp.example.com/mcp

The generated config contains only the URL. Do not add an Authorization header: Grok Bot uses OAuth discovery and PKCE to obtain its own access token.

Install or package this folder as a plugin, restart Grok Bot, then enable the connector. The first connection opens the approval page. Enter the same owner code stored in CURSOR_BRIDGE_SECRET.

Agent CLI flags used by the bridge

Defaults: --force on (full agentic tools). Set CURSOR_BRIDGE_MODE=ask for read-only Q&A, or plan for plan mode. Set CURSOR_BRIDGE_FORCE=0 to disable force when running in default agentic mode.

Add Composio beside this bridge

Corey Ganim's Grok Bot tip uses Composio Connect to go beyond a client's native connector catalog. Keep the two connections separate:

The .grok-plugin, .cursor-plugin, and .codex-plugin manifests here install only the Cursor Agent bridge. Composio traffic does not pass through this gateway. See the tutorial for the complete setup model and safety boundaries.

Grok Bot's visible-message limitation

Grok Bot currently emits a short visible message before every tool call, such as “I’ll pass that to Cursor Agent.” The plugin cannot hide or remove that host-level step. The bundled skill keeps it brief and prevents Grok Bot from impersonating Cursor Agent.

Security model

• fixed Cursor Agent executable; no shell invocation

• bounded prompt, output, timeout, payload, rate, and concurrency

• minimal child-process environment (API key forwarded only when configured)

• OAuth discovery, dynamic client registration, authorization code + PKCE, signed access tokens, and refresh tokens

• owner approval required; owner code never works as a bearer token

• host/origin checks, DNS-rebinding protection, localhost-only bind, log redaction, and filtered status output

• fail-closed startup if the endpoint, owner code, agent binary, or workspace is invalid

The OAuth provider is intentionally single-owner. Registered clients persist locally in a mode-0600 JSON file; pending approvals and authorization codes are in memory. Rotating CURSOR_BRIDGE_SECRET invalidates issued tokens.

Test and audit

python -m pip install -e '.[dev]'
python -m unittest discover -s tests -v
python src/privacy_scan.py --root .
python scripts/audit_git_history.py
python3 scripts/doctor.py

Also read SECURITY.md before exposing the endpoint.

License

MIT. See LICENSE.