\n\n[](https://github.com/4lador/leantime-mcp/actions/workflows/ci.yml)\n[](https://registry.modelcontextprotocol.io/v0.1/servers?search=leantime-mcp)\n[](https://crates.io/crates/leantime-mcp)\n[](LICENSE)\n\nAn unofficial [Model Context Protocol](https://modelcontextprotocol.io/) server for [Leantime](https://leantime.io/), 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.\n\nIt 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.\n\n**~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).\n\n**Documentation**: [Quick start](#quick-start) · [Configuration](#configuration) · [Safety](#safety) · [Tools](#tools) · [Troubleshooting](#troubleshooting) · [Harness setup](docs/harness-setup.md) · [Backup & recovery](docs/backup-restore.md) · [Migration from v1.x](migration-from-1.x.md) · [CHANGELOG](CHANGELOG.md) · [CONTRIBUTING](CONTRIBUTING.md) · [SECURITY](SECURITY.md)\n\n## Demo\n\nAn example session (abridged):\n\n> **You:** What's the status of the Acme launch project?\n>\n> **Agent** calls `leantime_project_context` — one call returning progress, health, sprint and milestones:\n>\n> ```json\n> { \"project\": { \"name\": \"Acme launch\", \"progress\": { \"percentDone\": 64.5, \"ticketsTotal\": 279, \"ticketsDone\": 180 } },\n> \"health\": { \"blocked\": 0, \"overdue\": 7, \"unassigned\": 3, \"openTotal\": 99 },\n> \"currentSprint\": { \"name\": \"Sprint 4\", \"status\": \"current\", \"daysRemaining\": 6, \"openTickets\": 8 } }\n> ```\n>\n> **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%.\n\n## Features\n\n- 42 tools: projects, tickets, subtasks, milestones, sprints, comments, time tracking, bulk operations\n- `leantime_project_context` — the whole project picture in one call (progress, health, sprint, milestones), under 4 KB\n- `dryRun: true` on every mutation — same validations, `from → to` diffs on updates, no write requests\n- `idempotencyKey` on creation tools — a retried call with an already-succeeded key replays the original result instead of writing a duplicate\n- Result envelopes: structured `truncated` on capped lists, `changed`/`unchanged` diffs on updates — agents see what a call actually did\n- `LEANTIME_MCP_PROFILE=readonly` — a server-wide execution profile that removes write capabilities entirely\n- Backup retention (`LEANTIME_MCP_BACKUP_RETENTION_DAYS`), atomic backup writes, and a restore manifest mapping every old→new id\n- Bulk operations up to 50 items, validated upfront (all-or-nothing on creates)\n- Backup & restore — snapshot a project to local JSON, rebuild it into a new project\n- Adaptive rate-limit retries, transparent to agents\n- Credentials in a local keyring (mode 0600) — harness configs hold a bare command\n- Deletes confirm-gated; `LEANTIME_MCP_DESTRUCTIVE_POLICY=deny` as an emergency stop\n- Per-instance tool management — disable what you don't use, read-only mode in two commands\n- Markdown → Leantime rich HTML, converted deterministically server-side\n\n## Install\n\n**Linux / macOS (x86_64, aarch64):**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/4lador/leantime-mcp/main/install.sh | sh\n```\n\n**Windows (PowerShell):**\n\n```powershell\nirm https://raw.githubusercontent.com/4lador/leantime-mcp/main/install.ps1 | iex\n```\n\nBoth 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).\n\n**Via cargo** (requires the Rust toolchain):\n\n```bash\ncargo install leantime-mcp # installs the leantmcp binary to ~/.cargo/bin\n```\n\n**From source:**\n\n```bash\ncargo build --release # → target/release/leantmcp\n```\n\n## Quick start\n\n```bash\nleantmcp url set https://your-instance.leantime.io # once\nleantmcp key set # once — hidden prompt\nleantmcp setup # writes the config\nleantmcp doctor # verify everything end-to-end\n```\n\nYour Leantime API key: **My Account → API Keys → Generate** on your instance.\n\n| Harness | Default scope | Config file |\n|---|---|---|\n| opencode | global | `~/.opencode/opencode.json` |\n| Claude Code | **project** | `./.mcp.json` |\n| Claude Desktop | global | `claude_desktop_config.json` (path per OS) |\n| Cursor | global | `~/.cursor/mcp.json` |\n| Codex | global | `~/.codex/config.toml` |\n\nEvery 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](docs/harness-setup.md).\n\n## Configuration\n\nCredentials live in named instance profiles — `~/.config/leantime/instances//` (`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.\n\n```bash\nleantmcp url show # resolved URL + where it comes from\nleantmcp key show # masked display (lt_h13…Fc3O)\nleantmcp key test # live validation against the instance\nleantmcp key rotate # mint a new key (same role), verify it live, replace the stored one\nleantmcp instance add … # multiple Leantime instances (see Harness setup)\n```\n\n`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.\n\n## Safety\n\nThis 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.\n\n- **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.\n- **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.\n- **Assignment is mandatory** on ticket/milestone creation (`editorId` validated against the real user list, or an explicit `unassigned: true`).\n- **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.\n- **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](docs/backup-restore.md).\n\n## Tools\n\n42 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.\n\n\nSupported Markdown subset (for descriptions and comments)\n\n| Markdown | Result |\n|----------|--------|\n| `#` … `####` | Headings (levels 5+ clamp to h4) |\n| blank-line separated text | Paragraphs (single newlines become line breaks) |\n| `- item` / `1. item` | Unordered / ordered lists (nesting supported) |\n| `- [ ] x` / `- [x] x` | Interactive checklists |\n| `**bold**`, `*italic*`, `~~strike~~` | Emphasis |\n| `` `code` `` and fenced ` ``` ` blocks | Inline and block code |\n| `[label](https://…)` | Links (http/https/mailto only) |\n| `> quote` | Blockquote |\n| `---` | Horizontal rule |\n\nRaw HTML in descriptions is escaped before reaching Leantime — it renders as literal text.\n\n\n\n\nAll 42 tools (click to expand)\n\n**Projects & clients**\n\n| Tool | Description |\n|------|-------------|\n| `leantime_list_projects` | List all projects |\n| `leantime_get_project` | Get project details |\n| `leantime_get_project_progress` | Get project progress metrics |\n| `leantime_create_project` | Create a project (Markdown details, clientId required) |\n| `leantime_update_project` | Update a project (patch — only provided fields change) |\n| `leantime_find_projects` | Search projects by name |\n| `leantime_list_project_users` | List users assigned to a project (valid editorId candidates) |\n| `leantime_list_clients` | List clients (clientId needed to create projects) |\n\n**Tickets**\n\n| Tool | Description |\n|------|-------------|\n| `leantime_list_tickets` | List tickets with filters (status, milestone, sprint, user, type, search) |\n| `leantime_get_ticket` | Get ticket details |\n| `leantime_create_ticket` | Create a ticket (Markdown description, mandatory assignment, subtasks via dependingTicketId; `dryRun` supported) |\n| `leantime_update_ticket` | Update a ticket (patch — only provided fields change; `dryRun` supported) |\n| `leantime_delete_ticket` | Delete a ticket (confirm-gated) |\n| `leantime_list_subtasks` | List a ticket's subtasks |\n| `leantime_my_tasks` | Open tickets assigned to a user (default: the API key owner) |\n| `leantime_get_ticket_options` | Priorities, efforts, kanban columns and ticket types |\n| `leantime_get_statuses` | Get status labels for a project |\n| `leantime_get_ticket_types` | Get ticket types for a project |\n\n**Comments**\n\n| Tool | Description |\n|------|-------------|\n| `leantime_list_comments` | List a ticket's discussion |\n| `leantime_add_comment` | Comment on a ticket (Markdown converted to rich HTML) |\n| `leantime_update_comment` | Edit a comment (Markdown) |\n| `leantime_delete_comment` | Delete a comment (confirm-gated) |\n\n**Time tracking**\n\n| Tool | Description |\n|------|-------------|\n| `leantime_log_time` | Log hours on a ticket (`add` accumulates, `set` is idempotent; `dryRun` supported) |\n| `leantime_get_ticket_time` | Total and per-day booked time for a ticket |\n| `leantime_list_timesheets` | List time entries between two dates |\n| `leantime_delete_timesheet_entry` | Delete a time entry (confirm-gated) |\n\n**Milestones**\n\n| Tool | Description |\n|------|-------------|\n| `leantime_list_milestones` | List milestones of a project |\n| `leantime_get_milestone` | Get milestone details |\n| `leantime_create_milestone` | Create a milestone (Markdown description, mandatory assignment; `dryRun` supported) |\n| `leantime_update_milestone` | Update a milestone (patch; `dryRun` supported) |\n| `leantime_get_milestone_progress` | Completion % (effort × priority weighted, Leantime's formula) |\n| `leantime_delete_milestone` | Delete a milestone (confirm-gated; its tickets are kept) |\n\n**Sprints**\n\n| Tool | Description |\n|------|-------------|\n| `leantime_list_sprints` | List sprints of a project |\n| `leantime_create_sprint` | Create a sprint |\n| `leantime_update_sprint` | Update a sprint (name/dates) |\n| `leantime_get_current_sprint` | Sprint in progress (or next upcoming), computed from dates |\n\n**Users**\n\n| Tool | Description |\n|------|-------------|\n| `leantime_list_users` | List all users (id, name) — for assignment |\n\n**Bulk operations**\n\n| Tool | Description |\n|------|-------------|\n| `leantime_bulk_create_tickets` | Create up to 50 tickets — validated upfront, Markdown converted, per-item results (`dryRun` supported) |\n| `leantime_bulk_update_tickets` | Update up to 50 tickets via patch — per-item results (`dryRun` supported) |\n| `leantime_bulk_schedule_tickets` | Schedule up to 50 tickets (sprint, dates) via patch |\n\n**Backup & context**\n\n| Tool | Description |\n|------|-------------|\n| `leantime_backup_project` | Dump a project to a timestamped local JSON file (milestones, tickets, sprints — the response is a summary only, not the data) |\n| `leantime_project_context` | Full project overview in one call (progress, health, sprint, milestones, ticket summary, recent activity) — under 4 KB, the agent's natural first call |\n\n\n\n## Backup & recovery\n\n```bash\nleantmcp backup --project 3 --full # snapshot incl. comments (~/.config/leantime/backups/, 0600)\nleantmcp restore backup.json # dry-run, then --confirm to execute\n```\n\nRestore 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](docs/backup-restore.md).\n\n## Troubleshooting\n\n- **Start with `leantmcp doctor`** — it checks the key file, permissions, config and the key against the live instance.\n- **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. Instances with generous limits are correspondingly faster.\n- **\"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.\n- **Key rejected** — `leantmcp key test` validates live; `leantmcp key rotate` mints a replacement and swaps it in.\n- **Windows** — the PowerShell installer puts the binary in `%USERPROFILE%\\.local\\bin`; make sure it is on `PATH`.\n- Still stuck? [Open an issue](https://github.com/4lador/leantime-mcp/issues).\n\n## Why this isn't for you\n\n- You want **vendor-supported, official integrations** — use [Leantime's official offerings](https://leantime.io); this project is independent and unofficial.\n- You need a **hosted/remote (HTTP) MCP server** — leantmcp is stdio-only and runs locally next to your MCP client.\n- You need **project deletion or hiding** — intentionally not exposed by this server.\n\n## Development\n\n```bash\ncargo build --release\ncargo test # parallel works — env-mutating suites hold locks\ncargo fmt --all --check && cargo clippy --all-targets -- -D warnings\n```\n\nA 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](CONTRIBUTING.md); CI runs unit tests on Linux, Windows and macOS plus an exhaustive e2e suite against the docker instance.\n\n## License\n\n[MIT](LICENSE)\n\nLeantime 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.\n",
"bytes": 15975,
"sha": "bd6b38f13732021480cc38c8d63ab1a5b9f9d7efde84d0724ce5303cd0817c73",
"repo_slug": "4lador/leantime-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_4lador_leantime_mcp_058bc4a3/readme"
}
![\"leantime-mcp\"](\"https://raw.githubusercontent.com/4lador/leantime-mcp/main/docs/hero.png\")
\n