Leantime MCP over HTTP

A stateless TypeScript MCP server for self-hosted Leantime. It exposes 66 tools over Streamable HTTP and talks to Leantime only through its JSON-RPC API at /api/jsonrpc using x-api-key.

It does not connect to MySQL and does not require Redis or its own database.

Architecture

ChatGPT / Claude / Codex
        |
        | HTTPS MCP + Bearer token
        v
https://mcp.example.com/mcp
        |
        | JSON-RPC + x-api-key
        v
https://leantime.example.com/api/jsonrpc

Related MCP server: Leantime MCP Bridge

Tool surface

Composed convenience tools

These orchestrate multiple Leantime calls or add aggregation/batch semantics:

• getFullProjectOverview — project + users + tasks + milestones + comments + timesheets, with partial-failure results.

• bulkAddTasks / bulkEditTasks — batch execution with a result for each item.

• addMilestonesForProject — batch milestone creation.

• scheduleTaskOnCalendar / scheduleDay — converts task selections into calendar blocks.

• breakdownTask — creates a supplied set of subtasks beneath a parent task.

• getTimesheetSummary — returns raw entries plus totals by project, user and day.

• getAllProjectComments / addProjectStatusUpdate — convenient project status/comment operations.

breakdownTask does not invent the decomposition itself. The AI client decides the subtasks and sends them to the tool; the MCP server executes them.

Sprints, Wiki, and Files

• Leantime's Kanban board is typically scoped to a sprint. Tasks created via addTask/bulkAddTasks are not assigned to any sprint by default (sprint: 0); use getAllSprints/getCurrentSprintId to find the right sprint ID, then set sprint in the task's values (via editTask/bulkEditTasks) to make it appear on the board.

• Wiki tools operate on Leantime's project documentation feature. createWiki makes a documentation space; createArticle adds a page inside it (values.canvasId should be the wiki's ID).

• getAllWikiHeadlines requires a real userId — Leantime's server errors on null there, unlike most other endpoints' optional userId params.

• File upload is intentionally not exposed. Leantime's JSON-RPC transport has no multipart/file support, and testing confirmed the server's upload endpoint rejects a plain-JSON payload with a server error — there is no working way to upload file bytes through this API. getFilesByModule (list) and deleteFile (delete) work normally since they carry no binary payload; uploads must go through Leantime's web UI.

1. Leantime API key

Create a Leantime API key for the user/role you want the MCP server to act as. The key's Leantime permissions still apply, so project reporting, cross-user timesheets and writes can be denied by Leantime even though the MCP tool exists.

2. Environment

LEANTIME_URL=https://leantime.example.com
LEANTIME_API_KEY=lt_your_real_key
MCP_BEARER_TOKEN=replace-with-a-separate-long-random-secret
PORT=3000

Generate the MCP-side secret separately:

openssl rand -hex 32

Do not reuse the Leantime API key as MCP_BEARER_TOKEN.

3. Coolify

A GitHub Actions workflow (.github/workflows/docker-publish.yml) builds this image and pushes it to GitHub Container Registry on every push to main (tagged :latest, :<short-sha>, and any v* release tag).

docker-compose.coolify.yml pulls that prebuilt image rather than building on the Coolify host:

image: ghcr.io/<your-github-owner>/<your-repo>:latest

Update the <your-github-owner>/<your-repo> placeholder to match your fork, and make sure the GHCR package is public (or add registry credentials in Coolify) so Coolify can pull it.

In Coolify, create a Docker Compose resource pointing at this repo and docker-compose.coolify.yml, then set:

LEANTIME_URL=https://leantime.example.com
LEANTIME_API_KEY=lt_your_real_key
MCP_BEARER_TOKEN=your-random-secret

Assign a domain to the service on container port 3000, for example at:

https://mcp.example.com

The MCP endpoint is:

https://mcp.example.com/mcp

Health check:

GET /health

4. MCP client

For clients that support remote Streamable HTTP and custom headers:

{
  "url": "https://mcp.example.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_MCP_BEARER_TOKEN"
  }
}

5. Test Leantime before MCP

Verify the API key directly first:

curl -sS 'https://leantime.example.com/api/jsonrpc' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_LEANTIME_API_KEY' \
  --data '{"jsonrpc":"2.0","id":1,"method":"leantime.rpc.Projects.Projects.getAll","params":{"showClosedProjects":false}}'

If that succeeds, the MCP server has a working backend connection.

6. Development

Requires Node.js 22+.

npm install
npm test
npm run build
npm start

Current tests cover JSON-RPC request/error handling, auth, project/task/milestone/goal/calendar/timesheet/comment/timer mappings, batch partial failures, project overview composition, timesheet aggregation, and the approved 45-tool MCP surface.

Native-value tools

Some create/edit tools intentionally accept a values object instead of trying to duplicate every Leantime field in the MCP schema. This keeps the wrapper forward-compatible with Leantime fields such as assignees, status IDs, dates, tags and custom metadata.

Important examples:

• addTask: include at least projectId and headline.

• editTask: include the ticket id plus fields to change.

• addMilestone: include projectId and headline.

• createGoal: current Leantime expects a target canvasId in values.

• editGoal: include id or itemId.

• addEvent / editEvent: use Leantime calendar value names; this wrapper ensures a non-empty description because current Leantime requires one.

• logTime: requires hours, kind, and one of date, dateString, or timestamp.

Security model

There are two independent credentials:

1. MCP bearer token — protects the public /mcp endpoint.

2. Leantime API key — determines what the MCP server may actually do in Leantime.

Keep the MCP service stateless and put HTTPS in front of it through Coolify/Traefik.