Cursor Background Composer MCP server

The Cursor Background Agent API Client is a TypeScript tool providing programmatic access to Cursor's Background Composer functionality. It helps you create, manage, and monitor background coding tasks through a CLI interface or an MCP server for AI assistant integration.

Installation

Install the package globally:

npm install -g cursor-api-client

Or clone and build locally:

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

Setting Up Authentication

1. Get Your Session Token

You need a Cursor session token to authenticate API requests:

Option A: Environment Variable (Recommended)

export CURSOR_SESSION_TOKEN="your_session_token_here"

Option B: Cookies File Create a cookies.json file with your Cursor session cookies:

[
  {
    "name": "WorkosCursorSessionToken", 
    "value": "your_session_token_here"
  }
]

2. Verify Setup

Test your configuration:

cursor-api test

Using the CLI

Managing Background Composers

List all background composers:

cursor-api list
cursor-api list --format json

Create a new background composer:

cursor-api create --task-description "Add user authentication to the app"
cursor-api create -d "Fix bug in payment processing" -r "https://github.com/user/repo.git"

Get detailed composer information:

cursor-api details --composer-id "your-composer-id"

Settings Management

Check web access status:

cursor-api web-access

Check privacy mode settings:

cursor-api privacy

Get all user settings:

cursor-api settings

Global Options

• --format, -f - Output format: json, table, raw (default: table)
• --verbose, -v - Enable verbose logging
• --token, -T - Override session token
• --help, -h - Show help

GitHub Workflow Integration

Automatically trigger background agents for each new GitHub issue with the included workflow.

Setup Steps

1. Configure the Cursor session token:

   • Go to your repository's Settings > Secrets and variables > Actions
   • Add a new repository secret named CURSOR_SESSION_TOKEN
   • Set the value to your Cursor session token

2. The workflow automatically:

   • Triggers when new issues are created
   • Analyzes the issue and creates a background composer task
   • Posts a comment confirming the agent activation

Using the API Client Programmatically

import { CursorAPIClient } from 'cursor-api-client';

const client = new CursorAPIClient('your-session-token');

// Create background composer
const result = await client.createBackgroundComposer({
  taskDescription: 'Add user authentication',
  repositoryUrl: 'https://github.com/user/repo.git',
  branch: 'main',
  model: 'claude-4-sonnet-thinking'
});

// List composers
const composers = await client.listComposers();

// Get settings
const settings = await client.getUserSettings();

MCP Server Usage

Start the MCP server for AI assistant integration:

cursor-api mcp-server

The Model Context Protocol server enables AI assistants to interact with the Cursor Background Composer functionality.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "cursor-background-composer" '{"command":"npx","args":["cursor-api-client","mcp-server"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-background-composer": {
            "command": "npx",
            "args": [
                "cursor-api-client",
                "mcp-server"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "cursor-background-composer": {
            "command": "npx",
            "args": [
                "cursor-api-client",
                "mcp-server"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect