Cursor Background Agent API Client

Powerful Node.js API client and CLI tool for Cursor Background Composer automation

A TypeScript-based API client that provides programmatic access to Cursor's Background Composer functionality. Create, manage, and monitor background coding tasks with both CLI and MCP (Model Context Protocol) server support.

Features

CLI Interface - Command-line tool for managing background composers
MCP Server - Model Context Protocol server for AI assistant integration
TypeScript Support - Full type safety and IntelliSense
Background Composer Management - Create, list, and monitor coding tasks
User Settings Control - Manage privacy mode and web access settings
Repository Integration - Automatic Git repository detection
Multiple Output Formats - JSON, table, and raw output formats

Installation

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

Setup

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 FileCreate 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

CLI Usage

List Background Composers

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

Create 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 Composer Details

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

Check Settings

cursor-api web-access    # Check agent web access
cursor-api privacy       # Check privacy mode settings  
cursor-api settings      # Get user settings

Available Commands

list - List all background composers
create - Create new background composer task
details - Get detailed composer information
web-access - Check agent web access status
privacy - Get privacy mode settings
settings - Get user settings
test - Test all API endpoints
mcp-server - Start MCP server

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 every new issue with the included GitHub Actions workflow.

Setup

Add the workflow file (already included in this repository):
- .github/workflows/issue-background-agent.yml
Configure the Cursor session token secret:
- 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
Enable the workflow:
- The workflow will automatically trigger when new issues are created
- It will analyze the issue and create a background composer task
- A comment will be posted on the issue confirming the agent was triggered

How it Works

When a new issue is created, the workflow:

Makes a direct API call to Cursor's background composer endpoint
Passes the complete issue information (title, body, author, labels, URL)
Posts a comment on the issue confirming the agent was triggered

The background agent will receive:

Issue title and description
Author information
Labels
Repository context
Direct link to the issue

Results will be available in the Cursor Background Composer interface.

Workflow Features

Automatic Triggering - Runs on every new issue
Fast Execution - Direct API call with no setup steps
Rich Context - Passes complete issue information to the agent
User Feedback - Comments on the issue to confirm activation
Repository Aware - Uses the current repository URL automatically

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Start MCP server in development
npm run mcp-server:dev

API Client Usage

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();

License

MIT License - see LICENSE file for details.

Cursor Background Agent API Client