keen

Keen

完整的 Atlassian 平台命令行工具和 MCP 服务。

---

通过单个 Go 二进制文件，提供 Jira、Confluence、Agile、Marketplace、Service Desk、Assets、Compass、Bitbucket 和 Admin 的 1,843 个 API 端点。本地同步由 SQLite 支持，并提供全文搜索。为 AI Agent 提供 MCP 服务。优先为自动化打造，其次才面向人类。

Keen 是什么？

每个要自动化的 Atlassian 工作流，都离不开一堆手工编写 JSON 请求体、再用脆弱的 jq 解析结果的 curl 调用。每个操作 Jira 的 AI Agent，执行几十次操作后都会触及速率限制。

Keen 用类型化命令、结构化输出、支持 FTS5 全文搜索的本地 SQLite 缓存，以及 MCP 服务取代了这一切，让 AI Agent 能够快速、不受限地访问整个 Atlassian 技术栈。

免费且开源。 Apache-2.0 许可证。无需账户。无遥测。

API 覆盖范围

API	端点数	提供的功能
Jira Platform v3	630	事项、转换、搜索、批量操作、字段、工作流、权限
Jira Agile	105	冲刺、看板、待办事项列表、史诗、排名、速率
Confluence	130	CQL 搜索、空间、标签、模板、附件、权限、内容状态
Confluence v2	252	页面、博客文章、空间、文件夹、数据库、白板、评论、附件、空间角色
Marketplace v2	143	插件、版本、供应商、分发、评价、报告
Service Desk	75	请求、队列、客户、SLA、审批
Assets	64	对象、对象架构和类型、AQL 搜索、导入（keen assets-...）。keen 会从站点中查找你的云和工作区 ID
Compass	11	组件的事件、指标值、附件和 API 规范
Teamwork Graph	18 个查询	组织架构（经理、直接下属、汇报链）、团队、某人创建、评论、提及和浏览过的工作，均通过 GraphQL 实现（Teamwork Graph）。另有 keen graphql，可执行任意只读查询
Bitbucket	300	仓库、拉取请求、流水线、分支、提交、代码片段、工作区（keen bitbucket-...）。无需令牌即可访问公开数据；访问私有数据需要 Bitbucket 范围的令牌（身份验证）
Admin	133	组织、目录、群组、域、策略、用户管理、用户配置（SCIM）、API 令牌和服务账户、数据丢失防护。需要管理员 API 密钥（身份验证）

你的前 5 分钟

# 1. Install (macOS or Linux with Homebrew; see Install for .deb, .rpm and Docker)
brew install imogenlabs/tap/keen

# 2. Save your credentials
mkdir -p ~/.config/keen
cat > ~/.config/keen/auth.json <<'JSON'
{ "base_url": "https://yoursite.atlassian.net", "username": "[email protected]", "password": "your-api-token" }
JSON
chmod 600 ~/.config/keen/auth.json

# 3. Check connectivity
keen doctor

# 4. Sync your Jira data locally
keen sync

# 5. Search instantly (no API calls)
keen search "authentication bug" --data-source local

在 id.atlassian.com/manage-profile/security/api-tokens 生成 API 令牌。

也可以使用环境变量，它们会覆盖文件中的设置：

export JIRA_CLOUD_PLATFORM_USERNAME="[email protected]"
export JIRA_CLOUD_PLATFORM_PASSWORD="your-api-token"
export JIRA_CLOUD_PLATFORM_URL="https://yoursite.atlassian.net"

安装

Homebrew（macOS 和 Linux）

brew install imogenlabs/tap/keen

这会同时安装 keen 和 keen-mcp。运行 brew upgrade keen 即可获取新版本；formula 会在每次发布后的 1 天内更新。

Debian、Ubuntu、Fedora、RHEL

每个版本都提供适用于 x86_64（amd64）和 arm64 的 .deb 和 .rpm 软件包。它们会将 keen 和 keen-mcp 安装到 /usr/bin。

# Debian, Ubuntu
curl -LO https://github.com/imogenlabs/keen/releases/latest/download/keen_linux_amd64.deb
sudo apt install ./keen_linux_amd64.deb

# Fedora, RHEL
curl -LO https://github.com/imogenlabs/keen/releases/latest/download/keen_linux_amd64.rpm
sudo dnf install ./keen_linux_amd64.rpm

在 arm64 上，请使用 keen_linux_arm64.deb 或 keen_linux_arm64.rpm。要升级，请用相同方式安装新版本的软件包。

Docker

该镜像托管在 GitHub 的注册表和 Docker Hub 上，支持 amd64 和 arm64：ghcr.io/imogenlabs/keen 或 smashingtags/keen。默认运行 keen-mcp。要运行 CLI，请在镜像名称后添加 keen 及其参数：

docker run --rm \
  -e JIRA_CLOUD_PLATFORM_URL=https://yoursite.atlassian.net \
  -e [email protected] \
  -e JIRA_CLOUD_PLATFORM_PASSWORD=your-api-token \
  ghcr.io/imogenlabs/keen keen get PROJ-42 --agent

添加 -v keen-data:/home/nonroot，即可在多次运行之间保留 keen sync 的本地副本。要将其用作 MCP 服务，请参阅 MCP Server 下的 Docker。

下载二进制文件

从 GitHub Releases 下载：

# macOS (Apple Silicon)
curl -L https://github.com/imogenlabs/keen/releases/latest/download/keen_darwin_arm64.tar.gz | tar xz
sudo mv keen_darwin_arm64/keen /usr/local/bin/
sudo mv keen_darwin_arm64/keen-mcp /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/imogenlabs/keen/releases/latest/download/keen_darwin_amd64.tar.gz | tar xz
sudo mv keen_darwin_amd64/keen /usr/local/bin/
sudo mv keen_darwin_amd64/keen-mcp /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/imogenlabs/keen/releases/latest/download/keen_linux_amd64.tar.gz | tar xz
sudo mv keen_linux_amd64/keen /usr/local/bin/
sudo mv keen_linux_amd64/keen-mcp /usr/local/bin/

# Linux (arm64)
curl -L https://github.com/imogenlabs/keen/releases/latest/download/keen_linux_arm64.tar.gz | tar xz
sudo mv keen_linux_arm64/keen /usr/local/bin/
sudo mv keen_linux_arm64/keen-mcp /usr/local/bin/

每个版本还会发布 checksums.txt。

从源代码构建

git clone https://github.com/imogenlabs/keen.git
cd keen
make build-all   # builds bin/keen and bin/keen-mcp

需要 Go 1.26.10 或更高版本。

每个版本的变更内容：CHANGELOG.md。

MCP Server

Keen 内置 MCP 服务（keen-mcp），可向 AI Agent 提供所有 keen 命令（1,939 个工具）。适用于 Claude Code、Cursor、Windsurf 以及任何兼容 MCP 的宿主。

它提供两个工具：keen_search 可查找适用于某项任务的工具（“转换一个问题”“列出看板上的冲刺”），并返回这些工具及其参数；keen_run 则按名称运行某个工具。逐个列出全部 1,939 个工具大约需要 50 万个 token，超过大多数模型的上下文容量，因此连接 keen 的应用还没开始工作就会耗尽上下文。如需获取完整列表，请在服务的环境中设置 KEEN_MCP_TOOLS=all。

工具调用通过 stdio 以 JSON-RPC 形式传入。在 keen-mcp 内部查找工具不会调用 Atlassian。运行工具则会调用 Atlassian，但 5 分钟内重复的读取请求会由 keen 的缓存响应，因此繁忙的 Agent 也能保持在 Atlassian 的速率限制之内。任何成功的写入都会清除缓存，因此写入后的读取会获取最新数据。设置 KEEN_MCP_CACHE=off 可让每次读取都实时获取数据。如果 Atlassian 已关闭某个工具对应的 API，结果会说明应改用什么。

来源：docs/diagrams/mcp-flow.drawio。

Claude Desktop 与 MCP 注册表

在 Mac 上，从最新版本下载 keen-mcp.mcpb 并打开：Claude Desktop 会安装 keen，并询问你的 Atlassian 站点、邮箱和 API token。keen 也已列入官方 MCP 注册表，名称为 io.github.imogenlabs/keen，并会随每次发布更新。

keen-mcp 会像 CLI 一样查找凭据：先检查环境变量，然后检查 ~/.config/keen/auth.json 或 config.toml。如果已经设置好 CLI，只需运行 claude mcp add --transport stdio keen -- keen-mcp 即可。要显式传入凭据：

Claude Code

claude mcp add --transport stdio keen \
  --env [email protected] \
  --env JIRA_CLOUD_PLATFORM_PASSWORD=your-api-token \
  --env JIRA_CLOUD_PLATFORM_URL=https://yoursite.atlassian.net \
  -- keen-mcp

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "keen": {
      "command": "keen-mcp",
      "env": {
        "JIRA_CLOUD_PLATFORM_USERNAME": "[email protected]",
        "JIRA_CLOUD_PLATFORM_PASSWORD": "your-api-token",
        "JIRA_CLOUD_PLATFORM_URL": "https://yoursite.atlassian.net"
      }
    }
  }
}

Windsurf

使用相同结构添加到 ~/.codeium/windsurf/mcp_config.json。

Docker

任何 MCP 宿主都可以直接从镜像运行 keen-mcp，而不必安装它。-e NAME 标志会将 env 中的值传入容器：

{
  "mcpServers": {
    "keen": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "JIRA_CLOUD_PLATFORM_URL", "-e", "JIRA_CLOUD_PLATFORM_USERNAME", "-e", "JIRA_CLOUD_PLATFORM_PASSWORD",
               "ghcr.io/imogenlabs/keen"],
      "env": {
        "JIRA_CLOUD_PLATFORM_URL": "https://yoursite.atlassian.net",
        "JIRA_CLOUD_PLATFORM_USERNAME": "[email protected]",
        "JIRA_CLOUD_PLATFORM_PASSWORD": "your-api-token"
      }
    }
  }
}

本地同步与离线搜索

Keen 会将 Atlassian 数据同步到本地 SQLite 数据库，并使用 FTS5 进行全文搜索。查询针对本地缓存运行，耗时不到 100 毫秒，无需访问 Jira Cloud API。

keen sync                                          # hydrate local cache
keen search "sprint bug" --data-source local        # FTS search (sub-100ms)
keen analytics                                      # analytics on synced data
keen stale --days 30                                # find stale items
keen orphans                                        # find orphaned items
keen load                                           # workload distribution

对于需要执行大量查询且不想触及 Atlassian 的速率限制的 AI Agent，这尤其有用。

Agent 模式

每条命令都支持 --agent，只需一个标志即可启用 JSON 输出、不显示交互式提示、使用紧凑格式并关闭颜色。此模式专为 AI Agent 使用而设计。

keen agile get-all-boards --agent
keen issue transitions get PROJ-42 --agent | jq '.results.transitions[] | {id, name}'

常用的 Jira 调用有简写形式：

keen find-issues --jql "project = PROJ AND status = 'In Progress'" --agent
keen get PROJ-42 --agent
keen transition PROJ-42 --transition-name "In Progress" --agent   # name resolved to its id
keen sprints 42 --state active --agent

开始处理某个问题时，只需一次调用即可获取与其相关的所有内容，并将结果控制在令牌预算范围内：

keen context PROJ-42 --org my-org --agent              # default --budget 8000

它会返回该问题、其父级、评论、关联问题、子任务、GitHub 拉取请求和 提交（参见问题的 GitHub 工作）以及关联的 Confluence 页面。 结果顺序为：问题、父级、GitHub 工作、关联问题和子任务、最新评论、Confluence 页面 以及较早的评论。无法纳入的内容会连同其大小列在 budget.omitted 下，不会悄无声息地丢弃。

关键标志

标志	作用
--agent	JSON + 无提示 + 紧凑格式（所有脚本调用都使用此标志）
--compact	仅显示关键字段（id、name、status、时间戳）
--json	强制使用 JSON 输出
--csv	CSV 输出
--dry-run	显示将要发送的内容，但不实际发送
--stdin	从 stdin 以 JSON 格式读取请求正文
--select "key,fields.summary"	仅保留这些字段（点分路径可访问嵌套字段）。字段拼写错误时会提供建议；但如果写入已成功执行，则会发出警告并打印完整响应
--output-summary[=N]	如果输出超过 N 字节（默认值为 4096），则将其保存到私有临时文件，并打印一行 JSON 摘要，其中包含文件路径、大小和记录数
--quiet	每行一个值
--data-source local	仅查询本地 SQLite 缓存

命令发现

keen which "transition an issue"   # the command for a task, in plain words
keen which "create page"           # one line per answer; "no match" when nothing fits
keen api                     # browse all API interfaces
keen api wiki                # browse Confluence endpoints
keen api agile               # browse Agile endpoints

常见工作流

Sprint 管理

keen agile get-all-boards --agent
keen agile get-all-sprints BOARD_ID --state active,future --agent
keen agile create-sprint --stdin <<< '{"name":"Sprint 5","originBoardId":42}'
keen agile move-issues-to-sprint-and-rank SPRINT_ID \
  --stdin <<< '{"issues": ["PROJ-42", "PROJ-43"]}'
keen agile partially-update-sprint SPRINT_ID --stdin <<< '{"state": "active"}'

发布跟踪

将 git 发布标签记录为 Jira 版本，并为已发布的问题添加标签：

# every release tag so far, plus an unreleased "next" for work merged since
keen release sync --repo-path . --project PROJ --backfill --head origin/main --dry-run
# after publishing a release: "next" becomes the tag, a fresh "next" is created
keen release sync --repo-path . --project PROJ --tag v1.4.0 --head origin/main

版本名称与标签相同，发布日期为该标签对应提交的日期，并关联到其 GitHub 发布。 问题会添加到第一个提交信息中包含其键作为 Fix Version 的发布版本；现有 Fix Versions 会追加，不会替换。

问题的 GitHub 工作

在分支名称、提交消息和 PR 标题中加入问题键，就像 Atlassian 建立关联时使用的格式一样（fix/PROJ-42-retry-uploads、fix: PROJ-42 retry failed uploads）。然后：

keen github links PROJ-42 --org my-org     # or --repo my-org/api, or run it inside a checkout

会列出该问题的所有拉取请求和提交，每项只列出一次，并注明发现来源：Jira 的开发面板（连接了 GitHub for Jira 应用时）、GitHub 对问题键的搜索结果，以及问题中指向 PR 的网页链接。GitHub 搜索会使用 KEEN_GITHUB_TOKEN、GH_TOKEN、GITHUB_TOKEN 或你的 gh 登录凭据。未配置的来源会显示警告，而不会导致失败。

问题生命周期

keen jira-cloud-platform-search and-reconsile-issues-using-jql-post \
  --jql "project = PROJ AND status != Done" --agent
keen issue transitions get PROJ-42 --agent
keen issue transitions do PROJ-42 --transition-id 41 --agent
keen issue comment add PROJ-42 --body "Done."    # plain text is wrapped into ADF

Confluence

keen wiki search-content-by-cql --cql "type=page AND space=DOCS" --agent
keen wiki create-page --space DOCS --title "Release notes" --stdin < notes.xhtml
keen wiki update-page PAGE_ID --stdin < notes.xhtml   # version bumped for you
keen wiki get-page PAGE_ID --agent
keen wiki get-content-descendants PAGE_ID --agent
keen wiki add-labels-to-content PAGE_ID --stdin <<< '[{"prefix":"global","name":"adr"}]'

页面正文采用 Confluence 存储格式（XHTML）；Markdown 不会转换。

Marketplace

keen addons get io.example.my-addon --agent
keen addons list-search --q "story points" --agent
keen addons versions get io.example.my-addon --agent

对比

特性	Keen	mcp-atlassian	Atlassian Rovo MCP	jira-cli	ACLI (Appfire)
端点	1,843	98 个工具	46+	仅 Jira	众多
本地缓存	SQLite + FTS5	无	无	无	无
MCP 服务	是	是	是（官方）	否	否
产品	9（Jira、Confluence、Agile、Marketplace、Service Desk、Admin、Assets、Compass、Bitbucket）	2（Jira、Confluence）	5	1	4
Server / Data Center	否	是	否	是	是
价格	免费（Apache-2.0）	免费（开源）	Cloud 版免费	免费（MIT）	$360-$6,195/年
二进制文件	单个 Go 二进制文件	Python（uvx、pip、Docker）	远程服务	单个 Go 二进制文件	需要 JVM
离线搜索	是	否	否	否	否

更多详情，以及何时选择其他方案：对比。

架构

keen CLI 和 keen-mcp 服务共享一套命令，可访问 1,843 个 REST 端点和 18 个 GraphQL 查询。调用会发送到 Atlassian；5 分钟内的重复读取会由短期响应缓存提供，而每次写入都会清空该缓存。keen sync 会将数据复制到本地 SQLite + FTS5 存储中，供 keen search 和离线读取（--data-source local，或在无法连接 Atlassian 时自动使用）使用。

来源：docs/diagrams/architecture.drawio（可在 draw.io 中编辑）。

重新生成

keen 根据 15 份官方 Atlassian OpenAPI 规范（位于 specs/）通过 CLI Printing Press 生成，之后再叠加自身的更改。规范列表集中在一处：scripts/regen/config.sh 中的 SPECS。一个脚本即可根据 Atlassian 当前的规范刷新 keen，同时保留这些更改：

git switch -c build/refresh-specs
scripts/regen/regen.sh        # download current specs, generate, merge onto keen
scripts/regen/check.sh        # build, tests, lint, vulnerabilities, old-name and help checks

工作原理：生成器之前的输出（重命名为 keen）以隐藏引用 refs/regen/base 的形式保存在 GitHub 上（它不是分支；regen.sh 会获取它）。regen.sh 根据当前规范重新生成，再以相同方式重命名输出，并将其三方合并到 keen 中。规范的更改会合入，keen 自身的修改则会保留。keen 手动编写的文件（README、文档、变更日志、补丁列表）始终保留 keen 的版本。scripts/regen/postfix.py 会将 keen 的既定规则应用到生成器首次添加的代码上。scripts/regen/placeholders.py 会为帮助示例中的每个参数设置合适的占位符（生成器会在每个 *Key 参数中填入 your-token-here），而 check.sh 会在占位符被还原时失败。

如果合并因冲突而停止，脚本会列出相关文件。请在它打印出的工作文件夹中解决冲突（scripts/regen/resolve.py ours|theirs <file> 会为整个文件选择一方），然后运行 scripts/regen/finish.sh。合并进入你的检出目录后，两个脚本都会删除它们创建的工作文件夹（通过 REGEN_WORK 指定的文件夹会保留）；无论以何种方式结束，check.sh 都会删除其构建文件夹。分支合并到 main 后，请按照 regen.sh 的说明推进基准。

若要查看自上次刷新以来 Atlassian 的更改，而不修改任何内容，请运行 scripts/regen/specdiff.py。它会列出每份规范中新增、移除或更改的操作。每周运行的 GitHub 工作流（.github/workflows/spec-check.yml）会执行相同的检查，在发现差异时创建一个 issue，并在 keen 更新到最新状态后关闭它，因此不会漏掉任何更改。

scripts/mcp-check.py <dir with keen and keen-mcp> 会像 AI 应用使用 MCP 服务那样，针对实时站点进行测试：它会用通俗的语言向 keen_search 提出十个日常任务，通过 keen_run 运行工具，并将答案与 CLI 的答案进行比较。如果正确的工具没有进入前三名，或者排在它前面的工具已被 Atlassian 停用，测试就会失败。使用 --claude 时，它还会将 keen-mcp 作为 Claude Code 唯一可用的工具，并检查它能否回答真实问题且不出现调用失败。它会从站点中选取测试数据，而 check.sh 会在运行实时冒烟测试的同时运行此测试。

若要添加 Atlassian API，只需在 SPECS 末尾添加一行 name=URL，然后运行上述两个命令。无需编辑其他内容。

组织结构图和 Teamwork Graph 命令来自 Atlassian 的 GraphQL 架构，而不是 OpenAPI 规范。scripts/regen/graphql.py 会读取该架构（无需登录），在 specs/graphql.json 中保留快照，并生成命令表；刷新时会运行该脚本，每周检查则会将实时架构与快照进行比较。

如果 Atlassian 弃用某个 API，生成器就会停止生成相应命令。请将其添加到 internal/compat/compat.go，以保留旧命令和 MCP 工具的名称，并告知用户替代方案。所有本地更改都列在 .printing-press-patches.json 中。

Atlassian 的规范中也保留了已弃用的 API，有时即使它们已经停用。scripts/regen/deprecated.py 会列出规范标记为已弃用的所有操作（刷新时会运行该脚本，若列表过期，check.sh 就会失败）；keen 会为这些命令和工具添加标记，并让 keen_search 将它们排在替代方案之后。如果某个操作开始返回 410 Gone，请将其添加到 internal/compat/deprecated.go 中的 RemovedEndpoints，并注明替代方案：keen 随后会将其隐藏，其命令和工具会指向替代方案，而 keen sync 会跳过它。

安全

有关漏洞报告，请参阅 SECURITY.md。Keen 从环境变量或 ~/.config/keen/auth.json 读取 API 凭据。如果使用该文件，请确保只有你本人可以读取（chmod 600）。本地 SQLite 数据库包含缓存的 API 响应，应视为敏感信息。

贡献

请参阅 CONTRIBUTING.md。欢迎提交错误修复。提交新功能的 PR 前，请先提出 issue。

许可证

Apache-2.0

---

由 Imogen Labs 构建