Leantime MCP (Unofficial)

leantime-mcp

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

一个面向 Leantime 的非官方模型上下文协议服务，采用 Agent 优先设计：它提供 42 个工具，支持试运行验证、批量操作、备份/恢复以及一次调用获取项目上下文，让 LLM 工具（opencode、Claude Code、Claude Desktop、Cursor、Codex 或任何 MCP 客户端）能够处理你的 Leantime 项目。

这是一个独立的开源集成，仅支持 stdio，在本地使用你自己的 API 密钥和实例运行。它并非旨在取代 Leantime 的官方产品；如需由供应商支持的集成，请使用官方方案。

约 3 MB 的独立二进制文件（rustls — 不依赖系统 OpenSSL）、约 1.2 ms 的启动中位数和约 5 MB 的空闲内存（握手后 VmRSS — 在 Linux x86_64 开发机器上测得，n=100 次启动）。

文档：快速入门 · 配置 · 安全性 · 工具 · 故障排除 · Harness 设置 · 备份与恢复 · 从 v1.x 迁移 · 更新日志 · 贡献指南 · 安全

演示

会话示例（节选）：

你： Acme launch 项目的状态如何？

Agent 调用 leantime_project_context — 一次调用即可返回进度、健康状况、冲刺和里程碑：

{ "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 已完成 64.5%（279 个工单中已完成 180 个）。目前有 99 个未关闭工单，其中 7 个已逾期、3 个未分配，没有受阻工单。Sprint 4 将在 6 天后结束，还有 8 个未关闭工单；正在进行的里程碑（PHASE 8）已完成 47.8%。

功能

• 42 个工具：项目、工单、子任务、里程碑、冲刺、评论、时间跟踪、批量操作
• leantime_project_context — 一次调用即可获取完整的项目概况（进度、状态、冲刺、里程碑），不到 4 KB
• 每项变更操作都支持 dryRun: true — 执行相同的验证；更新时显示 from → to 差异；不发送写入请求
• 创建工具支持 idempotencyKey — 使用已成功的键重试调用时，会重放原始结果，而不是写入重复数据
• 结果封装：达到上限的列表会显示结构化的 truncated，更新会显示 changed/unchanged 差异 — Agent 可以看到调用实际执行了哪些操作
• LEANTIME_MCP_PROFILE=readonly — 服务器级执行配置，可完全移除写入能力
• 备份保留策略（LEANTIME_MCP_BACKUP_RETENTION_DAYS）、原子备份写入，以及映射所有旧 ID→新 ID 的恢复清单
• 批量操作最多可处理 50 项，并会预先验证（创建操作要么全部成功，要么全部失败）
• 备份与恢复 — 将项目快照保存为本地 JSON，再将其重建为新项目
• 自适应速率限制重试，对 Agent 透明
• 凭据存储在本地密钥环中（模式为 0600）— 框架配置仅包含一个纯命令
• 删除操作需要确认；LEANTIME_MCP_DESTRUCTIVE_POLICY=deny 可用作紧急停止开关
• 按实例管理工具 — 禁用不使用的工具，只需两个命令即可切换为只读模式
• Markdown → Leantime 富文本 HTML，由服务器端确定性转换

安装

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

两个安装程序都会在安装前验证已发布的 SHA-256 校验和，若不匹配则中止。发行版二进制文件涵盖发布页面上的全部 5 个目标平台 — Linux（x86_64、aarch64）、Windows x86_64，以及 macOS（Intel、ARM）。

通过 cargo 安装（需要 Rust 工具链）：

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

从源代码构建：

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

快速开始

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

Leantime API 密钥：在你的实例中前往 My Account → API Keys → Generate。

框架	默认范围	配置文件
opencode	全局	~/.opencode/opencode.json
Claude Code	项目	./.mcp.json
Claude Desktop	全局	claude_desktop_config.json（路径因操作系统而异）
Cursor	全局	~/.cursor/mcp.json
Codex	全局	~/.codex/config.toml

生成的配置都是不含凭据的纯命令 — 二进制文件会在启动时从密钥环中读取凭据。项目级配置、--scope/--instance/--name 选项和多个实例，请参阅框架设置。

配置

凭据存储在具名实例配置文件中 — ~/.config/leantime/instances/<name>/（api-key，模式为 0600；以及 instance-url），并通过 default 文件指定默认实例。密钥从密钥环文件或环境中读取 — 不接受将其作为命令行参数传入（以避免写入 shell 历史记录），也不会记录密钥；密钥管理命令仅通过 CLI 提供，不会作为 MCP 工具公开。

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 环境变量仍可用作单次运行的覆盖值；LEANTIME_INSTANCE 用于选择配置文件。解析顺序：环境变量（显式覆盖）→ LEANTIME_INSTANCE 配置文件 → default 文件。

安全

本软件按原样提供，不提供任何担保（MIT）。它会代表你使用 API 密钥操作 Leantime——在允许 Agent 操作之前，请备份 Leantime 数据。

• 删除操作需要确认（默认要求 confirm: true；LEANTIME_MCP_DESTRUCTIVE_POLICY=deny 会直接拒绝删除，allow 则会在 CI 中跳过确认）。项目隐藏和删除功能不会开放。
• 试运行：每个变更工具都接受 dryRun: true——会执行验证，更新会解析 from → to 值（含状态标签），批量工具会返回每项预览，且不会发送写入请求。工具描述内置了三层 Agent 指引策略：值明确时直接执行；值由 Agent 自行选择时先试运行再确认；批量操作必须先试运行。
• 创建工单/里程碑时必须分配负责人（editorId 必须通过真实用户列表验证，或明确设置 unassigned: true）。
• 工具管理：已禁用的工具会从 tools/list 中省略（不占用上下文窗口），调用时会被拒绝并返回可执行的错误提示。只读模式：leantmcp tools disable all && leantmcp tools enable readonly。状态按实例配置文件存储。
• 优先备份：leantime_backup_project（MCP）或 leantmcp backup（CLI）可低成本地为项目创建快照——系统会指示 Agent 在批量修改前使用。请参阅备份与恢复。

工具

9 个领域共 42 个工具：项目与客户（8 个）、工单（10 个）、评论（4 个）、时间跟踪（4 个）、里程碑（6 个）、冲刺（4 个）、用户（1 个）、批量操作（3 个）、备份与上下文（2 个）。更新使用补丁 API——仅更改已提供的字段。描述遵循 Markdown 子集，并在服务端转换；输入中的原始 HTML 会经过转义。

支持的 Markdown 子集（用于描述和评论）

Markdown	结果
# … ####	标题（5 级及以上会限制为 h4）
以空行分隔的文本	段落（单个换行符会转换为换行）
- item / 1. item	无序/有序列表（支持嵌套）
- [ ] x / - [x] x	交互式清单
**bold**、*italic*、~~strike~~	强调
`code` 和围栏式 ``` 代码块	行内代码和代码块
[label](https://…)	链接（仅限 http/https/mailto）
> quote	引用块
---	水平线

描述中的原始 HTML 会在传递给 Leantime 前转义——并以原样文本呈现。

全部 42 个工具（点击展开）

项目与客户

工具	描述
leantime_list_projects	列出所有项目
leantime_get_project	获取项目详情
leantime_get_project_progress	获取项目进度指标
leantime_create_project	创建项目（详情支持 Markdown，必须提供 clientId）
leantime_update_project	更新项目（补丁——仅更改已提供的字段）
leantime_find_projects	按名称搜索项目
leantime_list_project_users	列出分配给项目的用户（可用的 editorId 候选项）
leantime_list_clients	列出客户（创建项目需要 clientId）

工单

工具	描述
leantime_list_tickets	按筛选条件列出工单（状态、里程碑、冲刺、用户、类型、搜索）
leantime_get_ticket	获取工单详情
leantime_create_ticket	创建工单（Markdown 描述、必须分配负责人；通过 dependingTicketId 添加子任务；支持 dryRun）
leantime_update_ticket	更新工单（补丁模式——仅更改提供的字段；支持 dryRun）
leantime_delete_ticket	删除工单（需确认）
leantime_list_subtasks	列出工单的子任务
leantime_my_tasks	列出分配给用户的未完成工单（默认使用 API 密钥所有者）
leantime_get_ticket_options	获取优先级、工作量、看板列和工单类型
leantime_get_statuses	获取项目的状态标签
leantime_get_ticket_types	获取项目的工单类型

评论

工具	描述
leantime_list_comments	列出工单讨论
leantime_add_comment	评论工单（将 Markdown 转换为富文本 HTML）
leantime_update_comment	编辑评论（Markdown）
leantime_delete_comment	删除评论（需确认）

时间跟踪

工具	描述
leantime_log_time	记录工单工时（add 累加，set 幂等；支持 dryRun）
leantime_get_ticket_time	获取工单的总登记工时和每日登记工时
leantime_list_timesheets	列出两个日期之间的工时记录
leantime_delete_timesheet_entry	删除工时记录（需确认）

里程碑

工具	描述
leantime_list_milestones	列出项目的里程碑
leantime_get_milestone	获取里程碑详情
leantime_create_milestone	创建里程碑（Markdown 描述、必须分配负责人；支持 dryRun）
leantime_update_milestone	更新里程碑（补丁模式；支持 dryRun）
leantime_get_milestone_progress	完成百分比（按工作量 × 优先级加权，采用 Leantime 的公式）
leantime_delete_milestone	删除里程碑（需确认；其工单会保留）

冲刺

工具	描述
leantime_list_sprints	列出项目的冲刺
leantime_create_sprint	创建冲刺
leantime_update_sprint	更新冲刺（名称／日期）
leantime_get_current_sprint	获取进行中的冲刺（或下一个即将开始的冲刺），根据日期计算

用户

工具	描述
leantime_list_users	列出所有用户（id、姓名），用于分配负责人

批量操作

工具	描述
leantime_bulk_create_tickets	创建最多 50 个工单——预先验证、转换 Markdown，并返回每项结果（支持 dryRun）
leantime_bulk_update_tickets	通过补丁更新最多 50 个工单——返回每项结果（支持 dryRun）
leantime_bulk_schedule_tickets	通过补丁为最多 50 个工单安排计划（冲刺、日期）

备份与上下文

工具	描述
leantime_backup_project	将项目导出到带时间戳的本地 JSON 文件（里程碑、工单、冲刺——响应仅包含摘要，不含数据）
leantime_project_context	通过一次调用获取完整的项目概览（进度、健康状况、冲刺、里程碑、工单摘要、近期活动）——小于 4 KB，是 Agent 自然的首次调用

备份与恢复

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

恢复操作会将备份写入新创建的项目，不会合并到现有项目中，也不会写入现有项目。大型项目通过日期窗口分页处理（尽力而为的快照，并非原子操作）。详情、环境变量和速率限制行为请参阅：备份与恢复。

故障排除

• 从 leantmcp doctor 开始 — 它会检查密钥文件、权限、配置，并使用密钥连接实时实例进行验证。
• 批量操作很慢 — 吞吐量受实例的速率限制控制（Leantime 默认限制为 10 req/min）；重试会自动进行，但处理 50 项的批次可能需要几分钟。在速率限制较低的实例上，每次调用最好分批处理 ≤ 10 项。当估算批次执行时间会超过 MCP 客户端的常见超时时间（约 60 s）时，dry-run 和执行结果中都会包含明确的 warnings 条目说明这一点。请求进度的 MCP 客户端（_meta.progressToken）也会在每次 API 调用和每次速率限制等待时收到 notifications/progress，从而让可感知超时的客户端保持调用不中断。
• 变更后出现“Ambiguous outcome”错误 — 请求发送后，实例返回了暂时性 5xx 错误；变更可能已应用，也可能未应用。重试前请先验证结果（重新读取实体）——盲目重试可能导致重复。
• 密钥遭拒 — leantmcp key test 会进行实时验证；leantmcp key rotate 会生成替代密钥并将其换入。
• Windows — PowerShell 安装程序会将二进制文件放在 %USERPROFILE%\.local\bin；请确保该路径已加入 PATH。
• 仍未解决？提出问题。

本工具不适合你的情况

• 你需要由供应商支持的官方集成 — 请使用 Leantime 的官方产品；本项目独立运营，未经官方认可。
• 你需要托管式／远程（HTTP）MCP 服务 — leantmcp 仅支持 stdio，并在 MCP 客户端旁边本地运行。
• 你需要删除或隐藏项目 — 本服务有意不提供此功能。

开发

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

仓库附带一个固定版本的 Docker Leantime + MySQL 实例（运行 docker compose up -d，然后运行 scripts/local-instance-bootstrap.sh）。完整的测试套件指南见 CONTRIBUTING.md；CI 会在 Linux、Windows 和 macOS 上运行单元测试，并针对 Docker 实例运行全面的端到端测试。

许可证

MIT

Leantime 是其各自所有者的产品。本项目是独立、未经官方认可的集成，与 Leantime 团队无关，也未获其背书。