Leantime MCP Server

The MCP Server is in beta and may include bugs. If you find one, please submit an issue here.

The MCP Server lets AI assistants and other MCP clients (Claude, Cursor, VS Code, Windsurf, …) work with your Leantime: read and update projects, tasks, milestones, goals, timesheets, calendar events and comments.

Clients connect directly to your Leantime's MCP endpoint — no bridge or extra package is needed:

https://YOURLEANTIMEURL/mcp

Installation (self-hosted only)

On Leantime Cloud the MCP Server is already available — skip to Create an access token.

1. Go to the Leantime App Marketplace and find the "MCP Server" app
2. After purchasing a license, enter the license key in Leantime
3. Click Install, then Enable

Requires Leantime 3.10.3 or later. There is nothing else to configure.

Create an access token

Personal Access Token (recommended) — go to your profile, open the "Personal Access Tokens" tab, create a token and copy it (it is only shown once). The token acts as you, so prompts like "What are my tasks today?" work, and the assistant only sees projects you can see. Send it as Authorization: Bearer YOUR_TOKEN.

API Key — admins can create API keys under Company Settings → API Keys (format lt_…). API keys are service accounts, not you, so "my tasks" refers to the API user. Good for automations. Send it as x-api-key: lt_….

Connect your AI client

Replace YOURLEANTIMEURL and YOUR_TOKEN in the examples below.

Claude Code

claude mcp add --transport http leantime https://YOURLEANTIMEURL/mcp --header "Authorization: Bearer YOUR_TOKEN"

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "leantime": {
      "url": "https://YOURLEANTIMEURL/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "leantime": {
      "type": "http",
      "url": "https://YOURLEANTIMEURL/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Windsurf

Same as Cursor, but in ~/.codeium/windsurf/mcp_config.json and with "serverUrl" instead of "url".

Claude Desktop

Claude Desktop's connectors don't support custom headers yet, so use the free mcp-remote helper (needs Node.js 18+). Add to claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "leantime": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOURLEANTIMEURL/mcp", "--header", "Authorization:${LEANTIME_AUTH}"],
      "env": { "LEANTIME_AUTH": "Bearer YOUR_TOKEN" }
    }
  }
}

Using the old leantime-mcp bridge?

The leantime-mcp npm package is deprecated and no longer needed. Replace it in your config with one of the setups above — your existing token keeps working — and uninstall it with npm uninstall -g leantime-mcp.

Test the connection

curl https://YOURLEANTIMEURL/mcp -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

A response containing "Leantime MCP Server" means you're connected.

Troubleshooting

• 401 Unauthorized — the token is missing, revoked or mistyped. If Leantime is behind a reverse proxy, make sure it forwards the Authorization header.
• 404 on /mcp — the MCP Server app isn't installed or enabled, or Leantime runs in a subfolder (use https://example.com/leantime/mcp).
• Empty results or "not allowed" — the token's user has no access to that project. MCP uses the same permissions as the Leantime web app.
• "My tasks" returns nothing — you're using an API key; use a Personal Access Token instead.
• 429 Too Many Requests — rate limit reached (default 300 requests/minute). Self-hosted admins can change it with LEAN_RATELIMIT_MCP.
• Self-signed certificate (local testing only) — for mcp-remote add "NODE_TLS_REJECT_UNAUTHORIZED": "0" to env. Never use this in production.

Security

• Always use HTTPS
• Prefer Personal Access Tokens, and revoke tokens you no longer use from your profile
• Every tool call runs with the token user's role and project access

For workflow ideas and example prompts, see Leantime's MCP Server Guide - Workflows & Use Cases.

Updated on: 04/10/2026