cursor-background-agent-api

This MCP server provides programmatic access to Cursor's Background Composer functionality via the Cursor Background Agent API client, enabling AI assistants and automation workflows to create, manage, and monitor background coding tasks. After building the project, start the MCP server alongside your client to enable Model Context Protocol interactions. You can then integrate the MCP server into your AI-enabled workflows to submit composer tasks, fetch status, and retrieve results, all through structured MCP messages and contexts.

To use the server locally, ensure you have a valid Cursor session token (via CURSOR_SESSION_TOKEN or a cookies.json file) and start the MCP server using the project's development commands. The server exposes endpoints and intents via MCP that allow you to create new background composers, list existing ones, fetch details, and check or update user settings related to privacy and web access. When interfacing through an MCP-enabled assistant, you can issue actions like createComposer, listComposers, and getComposerDetails, and the MCP layer will translate these into API calls to the Cursor service and return structured results for your agent.

Prerequisites:

• Node.js (recommended LTS version) and npm
• Git
• Access to the Cursor API token (see setup below)

Installation steps:

1. Install the package globally (or install locally and use scripts): npm install -g cursor-api-client

2. (Optional) Clone the repository and install dependencies: git clone https://github.com/mjdierkes/cursor-background-agent-api.git cd cursor-background-agent-api npm install

3. Build the project (if applicable): npm run build

4. Set up your environment:

   • Obtain a Cursor session token (via environment variable CURSOR_SESSION_TOKEN or cookies.json as described in the Setup section).
   • Ensure the MCP server can be started (see the Start MCP server script in package.json).

5. Start the MCP server (development): npm run mcp-server:dev

6. If you’re consuming via CLI or JS/TS client, install and configure the cursor-api-client as shown in the API Client Usage section of the README.

Tips and common considerations:

• Ensure CURSOR_SESSION_TOKEN is kept secure and not committed to version control.
• If you use cookies.json, place it in a secure, accessible location and reference it in your environment accordingly.
• The MCP server path may vary after build; if dist/server.js does not exist, verify your build output location in your build script and adjust the MCP args accordingly.
• Use the MCP start command in development as documented (npm run mcp-server:dev) to leverage hot-reload and easier testing.
• When integrating with an AI assistant, structure your MCP messages to align with the available commands: createComposer, listComposers, details, web-access, privacy, settings, test, and check the mcp-server status.
• If you encounter token-related errors, double-check that the token has the required permissions for Cursor Background Composer operations.
• Review the repository’s GitHub Actions workflow to understand how background agents are triggered for issues; you can adapt similar patterns for your tasks.