leantime-mcp

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

An unofficial Model Context Protocol server for Leantime, designed agent-first: it lets LLM tools (opencode, Claude Code, Claude Desktop, Cursor, Codex, or any MCP client) work on your Leantime projects through 42 tools with dry-run validation, bulk operations, backup/restore and one-call project context.

It is an independent, open-source integration — stdio only, running locally with your own API key and your own instance. It does not aim to replace Leantime's official offerings; if you want vendor-supported integrations, use those.

~3 MB self-contained binary (rustls — no system OpenSSL), ~1.2 ms median startup and ~5 MB idle memory (VmRSS after handshake — measured on a Linux x86_64 dev machine, n=100 spawns).

Documentation: Quick start · Configuration · Safety · Tools · Troubleshooting · Harness setup · Backup & recovery · Migration from v1.x · CHANGELOG · CONTRIBUTING · SECURITY

Demo

An example session (abridged):

You: What's the status of the Acme launch project?

Agent calls leantime_project_context — one call returning progress, health, sprint and milestones:

config.json

Copy

{ "project": { "name": "Acme launch", "progress": { "percentDone": 64.5, "ticketsTotal": 279, "ticketsDone": 180 } },
  "health": { "blocked": 0, "overdue": 7, "unassigned": 3, "openTotal": 99 },
  "currentSprint": { "name": "Sprint 4", "status": "current", "daysRemaining": 6, "openTickets": 8 } }

Agent: Acme launch is at 64.5% (180 of 279 tickets done). 99 tickets are open — 7 overdue, 3 unassigned, none blocked. Sprint 4 ends in 6 days with 8 open tickets; the milestone in progress (PHASE 8) sits at 47.8%.

Features

• 42 tools: projects, tickets, subtasks, milestones, sprints, comments, time tracking, bulk operations
• leantime_project_context — the whole project picture in one call (progress, health, sprint, milestones), under 4 KB
• dryRun: true on every mutation — same validations, from → to diffs on updates, no write requests
• idempotencyKey on creation tools — a retried call with an already-succeeded key replays the original result instead of writing a duplicate
• Result envelopes: structured truncated on capped lists, changed/unchanged diffs on updates — agents see what a call actually did
• LEANTIME_MCP_PROFILE=readonly — a server-wide execution profile that removes write capabilities entirely
• Backup retention (LEANTIME_MCP_BACKUP_RETENTION_DAYS), atomic backup writes, and a restore manifest mapping every old→new id
• Bulk operations up to 50 items, validated upfront (all-or-nothing on creates)
• Backup & restore — snapshot a project to local JSON, rebuild it into a new project
• Adaptive rate-limit retries, transparent to agents
• Credentials in a local keyring (mode 0600) — harness configs hold a bare command
• Deletes confirm-gated; LEANTIME_MCP_DESTRUCTIVE_POLICY=deny as an emergency stop
• Per-instance tool management — disable what you don't use, read-only mode in two commands
• Markdown → Leantime rich HTML, converted deterministically server-side

Install

Linux / macOS (x86_64, aarch64):

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

Windows (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.

Via cargo (requires the Rust toolchain):

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

From source:

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

Quick start

leantmcp url set https://your-instance.leantime.io   # once
leantmcp key set                                      # once — hidden prompt
leantmcp setup <your-harness>                         # writes the config
leantmcp doctor                                       # verify everything end-to-end

Your Leantime API key: My Account → API Keys → Generate on your instance.

Every generated config is a bare command with no credentials — the binary resolves them from the keyring at startup. Project-scoped setups, --scope/--instance/--name options and multiple instances: see Harness setup.

Configuration

Credentials live in named instance profiles — ~/.config/leantime/instances/<name>/ (api-key, mode 0600, and instance-url), with a default file naming the default. The key is read from the keyring file or environment — it is not accepted as a command-line argument (shell history) and is not logged; key commands are CLI-only and are not exposed as MCP tools.

leantmcp url show          # resolved URL + where it comes from
leantmcp key show          # masked display (lt_h13…Fc3O)
leantmcp key test          # live validation against the instance
leantmcp key rotate        # mint a new key (same role), verify it live, replace the stored one
leantmcp instance add …    # multiple Leantime instances (see Harness setup)

LEANTIME_URL / LEANTIME_API_KEY environment variables remain available as per-run overrides; LEANTIME_INSTANCE selects a profile. Resolution order: env (explicit override) → LEANTIME_INSTANCE profile → the default file.

Safety

This software is provided without warranty (MIT). It drives Leantime with your API key on your behalf — back up your Leantime data before letting agents operate on it.

• Deletes are confirm-gated (confirm: true required by default; LEANTIME_MCP_DESTRUCTIVE_POLICY=deny refuses them outright, allow skips the gate for CI). Project hiding/deletion is intentionally not exposed.
• Dry runs: every mutation tool accepts dryRun: true — validations run, updates resolve from → to values (with status labels), bulk tools return per-item previews, and no write request is sent. Agent guidance is built into the tool descriptions on a three-tier policy: direct execution for explicit values, dry-run-then-confirm when the agent chose the values itself, dry-run mandated for bulk.
• Assignment is mandatory on ticket/milestone creation (editorId validated against the real user list, or an explicit unassigned: true).
• Tool management: disabled tools are omitted from tools/list (no context-window cost) and calling one is refused with an actionable error. Read-only mode: leantmcp tools disable all && leantmcp tools enable readonly. State is stored per instance profile.
• Backup-first: leantime_backup_project (MCP) or leantmcp backup (CLI) snapshot a project cheaply — agents are instructed to use it before bulk modifications. See Backup & recovery.

Tools

42 tools across 9 domains: projects & clients (8), tickets (10), comments (4), time tracking (4), milestones (6), sprints (4), users (1), bulk operations (3), backup & context (2). Updates use the patch API — only provided fields change. Descriptions follow a Markdown subset converted server-side; raw HTML in input is escaped.

Backup & recovery

leantmcp backup --project 3 --full   # snapshot incl. comments (~/.config/leantime/backups/, 0600)
leantmcp restore backup.json         # dry-run, then --confirm to execute

Restore writes the backup into a newly created project — it does not merge into, or write to, an existing project. Large projects are handled via date-window pagination (best-effort snapshot, not atomic). Details, env vars and rate-limit behavior: Backup & recovery.

Troubleshooting

• Start with leantmcp doctor — it checks the key file, permissions, config and the key against the live instance.
• Bulk operations are slow — the instance's rate limit governs throughput (Leantime defaults to 10 req/min); retries are transparent but a 50-item batch can take minutes. Prefer chunks of ≤ 10 items per call on low-limit instances. When a batch is estimated to outlast typical MCP client timeouts (~60 s), the dry-run and execution envelopes carry an explicit warnings entry saying so. MCP clients that request progress (_meta.progressToken) also receive notifications/progress on every API call and every rate-limit wait, which lets timeout-aware clients keep the call alive.
• "Ambiguous outcome" error after a mutation — the instance returned a transient 5xx after the request was sent; the change may or may not have been applied. Verify the result (re-read the entity) before retrying — a blind retry can duplicate it.
• Key rejected — leantmcp key test validates live; leantmcp key rotate mints a replacement and swaps it in.
• Windows — the PowerShell installer puts the binary in %USERPROFILE%\.local\bin; make sure it is on PATH.
• Still stuck? Open an issue.

Why this isn't for you

• You want vendor-supported, official integrations — use Leantime's official offerings; this project is independent and unofficial.
• You need a hosted/remote (HTTP) MCP server — leantmcp is stdio-only and runs locally next to your MCP client.
• You need project deletion or hiding — intentionally not exposed by this server.

Development

cargo build --release
cargo test                          # parallel works — env-mutating suites hold locks
cargo fmt --all --check && cargo clippy --all-targets -- -D warnings

A pinned docker Leantime + MySQL instance ships with the repo (docker compose up -d, then scripts/local-instance-bootstrap.sh). The full test-suite guide lives in CONTRIBUTING.md; CI runs unit tests on Linux, Windows and macOS plus an exhaustive e2e suite against the docker instance.

License

MIT

Leantime is a product of its respective owners. This project is an independent, unofficial integration and is not affiliated with or endorsed by the Leantime team.