Home / MCP / Cursor Background Agent MCP Server

Cursor Background Agent MCP Server

Provides an MCP server for Cursor Background Composer automation, enabling task creation, management, and monitoring via CLI and API.

typescript

21stars

View on GitHub

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
    "mcpServers": {
        "cursor_mcp": {
            "command": "npm",
            "args": [
                "run",
                "mcp-server:dev"
            ],
            "env": {
                "CURSOR_SESSION_TOKEN": "YOUR_SESSION_TOKEN"
            }
        }
    }
}

You can run and manage the Cursor Background Agent MCP Server locally to automate background coding tasks, integrate with an AI assistant via Model Context Protocol, and expose a CLI for day-to-day control. This server enables you to create, list, and monitor background composers, adjust privacy and web access settings, and start the MCP endpoint for external clients to connect.

How to use

You operate this MCP server from a local development or production environment using the included CLI and MCP interface. Start the MCP server to accept connections from clients, then use the CLI commands to create, list, and inspect background composer tasks. The server surfaces user settings and web access status so you can tailor privacy and accessibility to your workflow.

How to install

Prerequisites: you need Node.js and npm installed on your system.

Step 1: Install the package globally so you can run the MCP server and CLI from anywhere.

npm install -g cursor-api-client

Step 2: Install dependencies and build locally if you prefer a local development setup.

git clone https://github.com/mjdierkes/cursor-background-agent-api.git
cd cursor-background-agent-api
npm install
npm run build

Step 3: Start the MCP server in development mode.

npm run mcp-server:dev

Configuration and usage notes

You can authenticate API requests by providing a Cursor session token either via the CURSOR_SESSION_TOKEN environment variable or by supplying a cookies.json file with the WorkosCursorSessionToken cookie. This server supports multiple output formats (json, table, raw) for CLI results and exposes commands to inspect and adjust settings.

Examples and common workflows

- Start MCP server in development mode and verify it’s running locally. - Use the CLI to create a new background composer task, fetch its details, and monitor progress. - Check web access and privacy settings to ensure your environment aligns with your security requirements.

Troubleshooting

If you encounter connectivity issues, verify that the MCP server process is running and that the correct TOKEN or cookies are provided. Check verbose logs with the --verbose flag when starting or querying the server to surface actionable error messages.

Available tools

createBackgroundComposer

Create a new background composer task with details about the task, repository, and model.

listComposers

List all background composer tasks with their statuses and IDs.

getUserSettings

Retrieve user settings including privacy mode and web access status.

startMCPServer

Start or manage the MCP server process for integration with clients.