Lancer MCP Server

Connect Cursor, Claude Desktop, ChatGPT, Kiro, or other MCP-compatible AI tools to your Lancer account. Manage projects, tasks, subtasks (todos), and milestones from your AI assistant.

Prerequisites

1. A Lancer account with at least one project
2. A personal access token (PAT) — create one in Lancer under Settings → Integrations → AI Tools

Quick start

All supported clients use the same mcpServers.lancer block:

{
  "mcpServers": {
    "lancer": {
      "command": "npx",
      "args": ["-y", "@lancerapp/mcp-server"],
      "env": {
        "LANCER_API_URL": "https://api.lancer.pro",
        "LANCER_PAT": "lnc_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}

Example configs for each client live in examples/.

Requires Node.js 18+. npx downloads the latest published package.

Local development (repo checkout)

When you are running the Lancer API locally, build this package and point Cursor at the built file from your repo root:

cd integrations/lancer-mcp
npm install
npm run build

{
  "mcpServers": {
    "lancer": {
      "command": "node",
      "args": ["integrations/lancer-mcp/dist/index.js"],
      "env": {
        "LANCER_API_URL": "http://localhost:3000",
        "LANCER_PAT": "lnc_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}

See examples/cursor.local.mcp.json. Use .cursor/mcp.json at the repo root so the relative path resolves correctly.

Cursor

| | | |---|---| | Global config | ~/.cursor/mcp.json | | Project config | .cursor/mcp.json |

1. Open Cursor → Settings → MCP, or edit the config file directly.
2. Add the lancer entry under mcpServers (merge with existing servers if needed).
3. Replace LANCER_PAT with your token and set LANCER_API_URL.
4. Restart Cursor or refresh the MCP panel.

See examples/cursor.mcp.json.

Claude Desktop

| | | |---|---| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

1. Quit Claude Desktop completely.
2. Open claude_desktop_config.json (create it if missing).
3. Add the lancer entry under mcpServers and save.
4. Restart Claude Desktop.

See examples/claude-desktop.config.json.

ChatGPT

ChatGPT Desktop (recommended for local MCP)

| | | |---|---| | macOS | ~/Library/Application Support/ChatGPT/mcp_config.json | | Windows | %APPDATA%\ChatGPT\mcp_config.json |

1. Edit mcp_config.json with the JSON block above.
2. In recent builds: Settings → Advanced → MCP Servers can manage configs in the UI.
3. Restart ChatGPT Desktop.

See examples/chatgpt.mcp.json.

ChatGPT on the web (chatgpt.com)

The web app requires a remote HTTPS MCP endpoint. The local npx stdio server used above is not supported in the browser UI.

To use ChatGPT on the web you would need a hosted MCP HTTP bridge (not included in v1). Use ChatGPT Desktop for the local Lancer MCP server, or expose your server via a secure tunnel if your plan supports remote MCP apps (Settings → Security → Developer mode → Apps).

Kiro

| | | |---|---| | Workspace | .kiro/settings/mcp.json | | User (global) | ~/.kiro/settings/mcp.json |

1. Command palette → Kiro: Open workspace MCP config (JSON) (or user config).
2. Add the lancer entry under mcpServers and save.
3. Kiro reconnects automatically — confirm lancer appears in the MCP servers panel.

See examples/kiro.mcp.json.

Local development

From the repo root:

cd integrations/lancer-mcp
npm install
npm run build

Point MCP at the built entrypoint instead of npx:

{
  "mcpServers": {
    "lancer": {
      "command": "node",
      "args": ["C:/path/to/lancer/integrations/lancer-mcp/dist/index.js"],
      "env": {
        "LANCER_API_URL": "http://localhost:3000",
        "LANCER_PAT": "lnc_pat_..."
      }
    }
  }
}

Programmatic config helpers are in src/mcp-client-configs.ts.

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | LANCER_API_URL | Yes | Base URL of the Lancer API (no trailing slash) | | LANCER_PAT | Yes | Account-scoped personal access token (lnc_pat_...) | | LANCER_ACCOUNT_ID | No | Override account id (normally discovered via GET /pat/context) | | LANCER_REQUEST_TIMEOUT_MS | No | HTTP timeout (default: 30000) | | LANCER_MAX_RESPONSE_BYTES | No | Max response body size (default: 5MB) | | LANCER_CLIENT_MAX_RPM | No | Client-side soft cap (default: 25/min; server enforces authoritative limits) |

Security

• HTTPS required for non-local LANCER_API_URL — the MCP client refuses plain HTTP in production to protect your PAT in transit
• Request timeout (30s default) prevents hung connections from tying up resources
• Response size cap (5MB default) blocks unexpectedly large payloads
• Client-side rate limit (25/min default) provides an early back-off before the server returns 429
• Server limits (authoritative): 30 requests/min and 2,000 requests/day per PAT — see PAT docs

Never commit your PAT to git or share MCP config files containing real tokens.

Available tools

Projects

| Tool | Description | |------|-------------| | list_projects | List all projects in the account | | get_project | Get one project by id | | create_project | Create a new project | | update_project | Update project fields |

Tasks

| Tool | Description | |------|-------------| | list_tasks | List tasks (filters: milestoneId, assignedTo, status) | | get_task | Get one task including subtasks | | create_task | Create a task with optional subtasks (todos) | | update_task | Update a task or replace subtasks | | delete_task | Delete a task |

Milestones

| Tool | Description | |------|-------------| | list_milestones | List milestones in a project | | get_milestone | Get one milestone | | create_milestone | Create a milestone (manager role required) | | update_milestone | Update a milestone | | delete_milestone | Delete a milestone |

Notes

• Tool responses are human-readable — project/task/milestone names and account names, not internal IDs
• Identify resources by name in follow-up tool calls (projectName, taskName, milestoneTitle)
• Todos are embedded subtasks on tasks — there is no separate todos API. Use the subtasks field when creating or updating tasks.
• Tokens are account-scoped. Each PAT only works for the account it was created in.
• File uploads, comments, billing, and chat are not available via PAT in v1.

Error messages

| HTTP status | Meaning | |-------------|---------| | 401 | Invalid or revoked PAT — create a new token in Lancer Settings | | 403 | Insufficient project role or missing PAT scope | | 404 | Project, task, or milestone not found | | 422 | Validation error — check required fields (e.g. task name, status) |

Client config reference

| Client | Config path | Transport | |--------|-------------|-----------| | Cursor | ~/.cursor/mcp.json or .cursor/mcp.json | stdio (local) | | Claude Desktop | claude_desktop_config.json | stdio (local) | | ChatGPT Desktop | mcp_config.json | stdio (local) | | ChatGPT (web) | Settings → Apps | remote HTTPS only | | Kiro | .kiro/settings/mcp.json | stdio (local) |

Publishing (maintainers)

Releases are published to npm as @lancerapp/mcp-server from GitHub Actions.

1. Create the npm org lancerapp (first time only) and a granular token with publish access.
2. Add the token as the repo secret NPM_TOKEN.
3. Bump version in package.json and commit.
4. Tag and push:

git tag mcp-server-v0.1.0
git push origin mcp-server-v0.1.0

The tag must match package.json (mcp-server-v + version). Provenance signing is omitted because this GitHub repo is private. After the first publish, you can switch the npm package to Trusted Publishing for this workflow and drop the long-lived token.