leantime-mcp

# leantime-mcp

- MCP Registry name: `mcp-name: io.github.4lador/leantime-mcp`

<p align="center">
  <img src="https://raw.githubusercontent.com/4lador/leantime-mcp/main/docs/hero.png" alt="leantime-mcp" width="600">
</p>

[![CI](https://github.com/4lador/leantime-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/4lador/leantime-mcp/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-8A2BE2)](https://registry.modelcontextprotocol.io/v0.1/servers?search=leantime-mcp)
[![crates.io](https://img.shields.io/crates/v/leantime-mcp)](https://crates.io/crates/leantime-mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io/) server for [Leantime](https://leantime.io/), enabling LLM-powered tools (opencode, Claude Code, Claude Desktop, Cursor, Codex, or any MCP client) to interact with your Leantime projects.

**~3 MB self-contained binary** (rustls — no system OpenSSL), **1.2 ms median startup** (measured over 100 spawns), **~5 MB idle memory** (VmRSS after handshake).

**Documentation**: [Migrating from v1.x](#migrating-from-v1x) · [Key management](#key-management) · [Safety](#safety-destructive-operations) · [Available MCP Tools](#available-mcp-tools) · [Development](#development) · [CHANGELOG](CHANGELOG.md) · [CONTRIBUTING](CONTRIBUTING.md) · [SECURITY](SECURITY.md) · [LICENSE](LICENSE)

## What's new in v2.5.0

The v2.3.2 → v2.5.0 series (all shipped 2026-09-08):

- **Date-window pagination** (v2.4.0) — completeness fetches (backup, restore verification, project_context) are immune to the API's per-call limit: windows are bisected by modification date until everything fits, with id-deduplication so concurrent modifications can only produce duplicates, never losses.
- **Concurrent `--full` backups** (v2.5.0) — `LEANTIME_MCP_BACKUP_CONCURRENCY` (1-8, default 1) fetches comments in parallel on generous instances; results stay in ticket order, the backup file is identical whatever the concurrency.
- **Fixes** — silent truncation at the fetch limit (v2.3.2 — now configurable via `LEANTIME_MCP_FETCH_LIMIT` with explicit warnings), and the `status` label filter returning the wrong tickets (v2.3.3 — labels now resolve to their IDs).
- **Installable via cargo** — `cargo install leantime-mcp`, and listed on the official [MCP Registry](https://registry.modelcontextprotocol.io).

Earlier releases — dry-run validation, `leantime_project_context`, backup/restore, the Rust rewrite — see the [CHANGELOG](CHANGELOG.md).

## Migrating from v1.x

The keyring, credentials and harness configs are **fully compatible** — the v2 binary is a drop-in replacement:

- **Your keyring works as-is**: `~/.config/leantime/instances/<name>/` is unchanged since v1.7.0. Both profiles and the `default` file resolve identically.
- **Your install URL still works**: `curl -fsSL https://raw.githubusercontent.com/4lador/leantime-mcp/main/install.sh | sh` delivers the v2 binary at the same location (`~/.local/bin/leantmcp`). The installer verifies the SHA-256 checksum as before.
- **Your harness configs need no change**: they point to `~/.local/bin/leantmcp` (bare command) — replacing the binary replaces the server. Restart your MCP session to pick up the new version.
- **The v1.x source code is preserved** on the [`frozen-legacy-ts`](https://github.com/4lador/leantime-mcp/tree/frozen-legacy-ts) branch. It will not receive updates or security fixes.

Why the rewrite? The v1.x binary embedded the Deno/V8 runtime:

| | v1.x (Deno/TypeScript) | v2.0.0 (Rust) |
|---|---|---|
| Binary size | ~100 MB | **~3 MB** |
| Startup | ~200 ms | **1.2 ms** (median, n=100) |
| Memory (idle) | ~50 MB | **~5 MB** (VmRSS) |
| Runtime deps | Deno/V8 embedded | **none (rustls)** |

## Features

- Full project-management coverage: projects, clients, tickets, subtasks, milestones, sprints, comments, time tracking and **bulk operations** (42 tools)
- **`leantime_project_context`**: a composite first-call tool that hydrates full project context (progress, health, sprint, milestones, activity) in one round-trip — agents start reasoning instead of paging through lists
- **Dry runs**: every mutation tool accepts `dryRun: true` — same validations, `from → to` diffs on updates, per-item previews on bulk, zero API writes. Agents are instructed to dry-run first on conversational-intent updates and inferred creates, and always on bulk batches
- **Backup & recovery**: `leantmcp backup [--full]` snapshots a project (plus `leantmcp restore` to rebuild it into a new project), and `leantime_backup_project` lets agents trigger a cheap backup before bulk modifications
- **Multiple Leantime instances**: named profiles (`instance add`, `instance use`), one server per instance in any harness — still zero secrets
- **Automatic 429 retry**: adaptive backoff that discovers the instance's rate limit from response headers — agents never handle rate limiting
- Deterministic Markdown → rich HTML descriptions and comments: formatting is applied server-side, so everything is always properly rendered in Leantime's editor
- Mandatory assignment on ticket/milestone creation: the server rejects calls that don't assign a user (or explicitly opt out)
- Destructive operations gated behind explicit confirmation (`LEANTIME_MCP_DESTRUCTIVE_POLICY`)
- v3.7.x API quirks handled server-side: scoping filters, session-less API keys, id mangling, array-wrapped ids

## Install

**Linux / macOS (x86_64, aarch64):**

```bash
curl -fsSL https://raw.githubusercontent.com/4lador/leantime-mcp/main/install.sh | sh
```

**Windows (PowerShell):**

```powershell
irm https://raw.githubusercontent.com/4lador/leantime-mcp/main/install.ps1 | iex
```

Both installers verify the published SHA-256 checksum before installing and abort on mismatch. Release binaries cover **all 5 targets** — Linux (x86_64, aarch64), Windows x86_64 and macOS (Intel, ARM) — on the [releases page](https://github.com/4lador/leantime-mcp/releases).

**Via cargo** (requires the Rust toolchain):

```bash
cargo install leantime-mcp   # installs the leantmcp binary to ~/.cargo/bin
```

**From source:**

```bash
cargo build --release   # → target/release/leantmcp
```

## How it works

- `leantmcp` is a **stdio MCP server**: your harness (opencode, Claude Code, Claude Desktop, Cursor, Codex…) spawns it at session start and stops it at session end. No daemon, no port, nothing runs in the background.
- **Credentials never live in harness configs.** The binary resolves them at startup: environment variables first (per-run override), then the keyring — `~/.config/leantime/instances/<name>/` (`api-key` mode 0600, `instance-url`). One keyring, shared by every harness you use — .
- That fallback is what makes every config below a **bare command with no secrets**: there is nothing sensitive to put in a config file in the first place.

## Setup

The universal flow, for every harness:

```bash
leantmcp url set https://your-instance.leantime.io   # once
leantmcp key set                                      # once — hidden prompt
leantmcp setup <your-harness>                         # writes the config (see table)
                                                      # bare `leantmcp setup` = `setup opencode`
leantmcp doctor                                       # verify everything end-to-end
```

```bash
leantmcp setup <harness> [--scope global|project] [--instance PROFILE] [--name SERVER]
```

Options:
- `--scope global|project` — where the config lives: machine-wide or committed to the repo root (default per harness, see table). Project-scoped files are designed to be committed to Git.
- `--instance PROFILE` — pin a keyring instance profile: the config gets a bare command + `LEANTIME_INSTANCE` env block, and the binary resolves that profile's credentials from the keyring at startup. Without it, the active/default instance is used.
- `--name SERVER` — the server key in the config (default: `leantime`) — for multiple instances side by side (e.g. `leantime` + `leantime-staging`).

| Harness | Default scope | Project file | Global file |
|---|---|---|---|
| opencode | global | `./opencode.json` (merges with global; `{file:}` pointers, git-safe) | `~/.opencode/opencode.json` |
| Claude Code | **project** (its committable form) | `./.mcp.json` | user scope via the `claude` CLI (printed for you) |
| Claude Desktop | global (GUI app — no project concept) | — | `claude_desktop_config.json` (path per OS) |
| Cursor | global | `./.cursor/mcp.json` (merge) | `~/.cursor/mcp.json` (merge) |
| Codex | global | `./.codex/config.toml` (trusted projects only) | `~/.codex/config.toml` |

All configs are **bare commands with no secrets**: the binary resolves credentials from `~/.config/leantime/instances/` at startup — there is nothing sensitive to put in a config file, which is what makes project-scoped files safe to commit.

The config a harness ends up with is simply:

```json
{
  "mcpServers": {
    "leantime": {
      "command": "/absolute/path/to/leantmcp"
    }
  }
}
```

### Per-project setup

```bash
cd my-repo
leantmcp setup cursor --scope project --instance staging --name leantime-staging
git add .cursor/mcp.json && git commit
```

Everyone on the team who clones the repo gets the server declaration for free; each member's own keyring provides their credentials. No secrets in the file.

### Any other MCP client

`leantmcp` is a standard stdio MCP server: point your client at the binary, no environment variables required (the keyring provides them). `LEANTIME_URL` / `LEANTIME_API_KEY` environment variables remain available as per-run overrides. Protocol revisions `2024-11-05` and `2025-06-18` are supported and negotiated at handshake (the client's version is echoed when known). All 42 tools carry MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients can group, gate and cache them intelligently.

### Multiple insta