Jira MCP 服务器（只读）

一个本地 MCP 服务器，让 Claude Code 拉取 Jira 工单上下文（问题详情、评论线程、工单周围的引用图以及 JQL 搜索结果），并以紧凑的 Markdown 呈现。可以获取图片附件（例如 UI 缺陷工单上的截图）供 Claude 进行视觉分析。

它刻意不能做什么

该服务器严格只读。它不暴露任何创建、更新、转换、删除或评论的工具。强制措施是分层的：

1. 在代码中： 每个 HTTP 请求都通过一个仅允许 GET 的辅助函数，但有一个白名单例外：POST /rest/api/3/search/jql，这是 Atlassian 要求以 POST 发送的读取操作。任何其他方法都会引发 ReadOnlyViolationError，因此未来添加写入调用的编辑会大声失败。

2. 在凭据级别： 仅使用读取范围（如下）创建 API 令牌，这样即使有 bug 也无法写入。

Related MCP server: JIRA MCP Server

工具

设置

1. 创建 Atlassian API 令牌

1. 前往 https://id.atlassian.com/manage-profile/security/api-tokens。

2. 选择使用范围创建 API 令牌（Atlassian 正在弃用无范围令牌）。

3. 选择 Jira 应用，并仅选择以下范围：

   • read:jira-work

   • read:jira-user

4. 立即复制令牌；它只显示一次。

较旧的无范围令牌也可以使用；服务器会自动处理两者（见下文）。

2. 配置 .env

cp .env.example .env   # then edit

必需的键（这是整个配置表面）：

.env 已被 gitignore；切勿提交它。真实环境变量优先于该文件。该文件位于项目目录（而非工作目录）的相对位置，因此无论从何处启动，服务器都能找到它。

3. 安装依赖

使用 uv（首选，因为此仓库有 uv.lock）：

uv sync

或者使用普通 pip 安装到虚拟环境：

python -m venv .venv
.venv/bin/pip install -r requirements.txt   # Windows: .venv\Scripts\pip

4. 使用 --check 验证

.venv/bin/python -m jira_mcp --check            # connectivity + auth only
.venv/bin/python -m jira_mcp --check PROJ-123   # also fetch a ticket in full

这会打印是否找到 .env、选择了哪个基础 URL（以及是否需要 cloud-ID 回退）、已认证的账户，以及当给定键时，Claude 将看到的工单的确切内容。

有范围与无范围令牌：基础 URL 问题

• 无范围令牌适用于你的站点 URL，https://<site>.atlassian.net。

• 有范围令牌针对同一 URL 会静默失败，返回看似匿名的响应。它必须改为调用 https://api.atlassian.com/ex/jira/{cloudId}。

你无需知道自己持有哪种类型。启动时，服务器使用 GET /rest/api/3/myself 探测站点 URL；如果未返回真实账户，它会从 {site}/_edge/tenant_info 获取你的 cloud ID，并针对 api.atlassian.com 重试。获胜者会在进程生命周期内缓存，并记录到 stderr。

如果检测失败：_edge/tenant_info 不属于 Atlassian 正式支持的 REST API（尽管 Atlassian 自己的支持文档指向它），因此它可能会更改。在这种情况下，在 .env 中设置 ATLASSIAN_CLOUD_ID 以跳过检测；错误消息会告诉你何时适用。你几乎不需要它。

PyCharm 设置

1. 解释器： 设置 → 项目 → Python 解释器 → 添加解释器 → 现有 → 选择项目目录中的 .venv/bin/python。（如果你运行了 uv sync，虚拟环境已存在并安装了所有内容。）

2. 用于调试的运行配置： 运行 → 编辑配置 → + → Python：

   • 运行： 模块 jira_mcp（选择“模块”而不是“脚本路径”）

   • 参数： --check PROJ-123

   • 工作目录： 项目根目录（任何目录都可以，但这样更整洁）

现在你可以在任何地方设置断点（例如在 client.py 中）并调试真实请求。否则，运行中的 MCP 服务器内部的错误是不可见的。

连接到 Claude Code

使用虚拟环境的 Python 绝对路径；当 Claude Code 启动服务器时，裸 python 不会解析到虚拟环境。

macOS/Linux：

claude mcp add jira -- /path/to/PythonProject/.venv/bin/python -m jira_mcp

Windows：

claude mcp add jira -- C:\path\to\PythonProject\.venv\Scripts\python.exe -m jira_mcp

注意：

• -- 之后的所有内容都是 Claude 运行的命令；之前的所有内容都是 Claude 自己的选项。

• 默认范围是 local（仅你自己，仅此项目，存储在 ~/.claude.json 中）。添加 --scope project 以通过已检入的 .mcp.json 共享，或添加 --scope user 以在所有项目中使用。

验证已连接

在 Claude Code 会话中：

• 运行 /mcp；jira 服务器应列为已连接，并带有六个工具。

• 或者直接问：“使用 whoami 检查 jira 连接”。

故障排除

给 Python 新手的注意事项

• 虚拟环境（.venv/）是 Python 的项目本地副本，加上此项目的包：相当于 node_modules，但解释器本身也在其中。这就是为什么必须给 Claude Code 提供 .venv/bin/python 的绝对路径：没有全局安装可依赖。

• asyncio.run(...) 是必需的，因为 Python 中的异步函数不会仅通过调用就运行；调用一个会返回协程对象，必须有东西来驱动它。没有像 Node 那样的环境事件循环；asyncio.run() 创建一个循环，运行一个协程直到完成，然后拆除循环。MCP 服务器通过 mcp.run() 在内部执行此操作；--check 模式显式执行。

• 装饰器（@mcp.tool）是接收其下方定义的函数并注册/包装它的函数，就像在定义时应用中间件工厂。FastMCP 的装饰器读取函数的名称、类型提示和文档字符串，以生成 Claude 看到的 MCP 工具架构；文档字符串就是工具的 API 文档。

• python -m jira_mcp 运行包的 __main__.py，这是 Python 最接近 npm bin 条目的东西。它可以从任何目录运行，因为 uv sync 已将项目安装到虚拟环境中。