JIRA MCP Server (Async)

JIRA MCP 服务（异步）

一个通过 stdio 传输方式集成 JIRA 的异步 Model Context Protocol（MCP）服务。支持 Atlassian Cloud 和 Server/DC 实例。

MCP 工具

6 个工具覆盖完整的问题生命周期，另有 2 个提示词模板：

工具	描述	关键参数
jira_search_issues	使用 JQL 搜索问题（分页）	jql、max_results、start_at
jira_get_issue	获取问题详情、评论和链接；可选获取子任务和工作流转换	issue_key、include_subtasks、include_transitions
jira_create_issue	创建新问题	project_key、summary、description、issue_type_name
jira_update_issue	更新现有问题的字段，可选添加评论	issue_key、summary、description、assignee、priority、labels、comment
jira_transition_issue	通过工作流转换推进问题	issue_key、transition_id、comment
jira_get_create_meta	创建问题前获取必填字段和允许值	project_key、issue_type

功能

• Cloud + Server/DC：通过 JIRA_USER_EMAIL 环境变量自动检测部署类型
• 令牌优化：转换 API 响应，使令牌数量减少 40-60%
• ADF 支持：读取和写入 Atlassian Document Format（Cloud v3）
• 连接池：使用 aiohttp，池大小可配置
• 速率限制：内置限流，在遇到 429 时采用指数退避
• 易于测试：可通过 _set_client() 注入客户端，可为 HTTP 级测试注入会话，包含 113 个单元测试

设置

先决条件

• Python 3.13+
• uv 包管理器
• JIRA API 令牌

安装

git clone https://github.com/judexzhu/mcp-jira.git
cd mcp-jira
uv sync
cp config.env.example .env
# Edit .env with your JIRA credentials

环境变量

变量	描述	默认值	必填
JIRA_SERVER_URL	JIRA 实例 URL	—	是
JIRA_API_TOKEN	JIRA API 令牌	—	是
JIRA_USER_EMAIL	用于 Cloud Basic Auth 的邮箱（启用 Cloud 模式）	—	仅 Cloud
MAX_CONCURRENT_REQUESTS	最大并发请求数和速率限制（请求/秒）	2	否
REQUEST_TIMEOUT	HTTP 请求超时（秒）	30	否
CONNECT_TIMEOUT	HTTP 连接超时（秒）	10	否
LOG_LEVEL	日志级别	ERROR	否
LOG_TO_STDOUT	启用 stdout 日志记录（会破坏 MCP stdio）	false	否

Claude Desktop

将以下内容添加到 Claude Desktop MCP 配置中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-jira", "python", "jira_mcp_server.py"],
      "env": {
        "JIRA_SERVER_URL": "https://your-company.atlassian.net",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_USER_EMAIL": "[email protected]"
      }
    }
  }
}

Claude Code

将以下内容添加到 Claude Code MCP 设置中（.claude/settings.json 或全局 ~/.claude/settings.json）：

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-jira", "python", "jira_mcp_server.py"],
      "env": {
        "JIRA_SERVER_URL": "https://your-company.atlassian.net",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_USER_EMAIL": "[email protected]"
      }
    }
  }
}

也可以通过 CLI 添加：

claude mcp add jira \
  -e JIRA_SERVER_URL=https://your-company.atlassian.net \
  -e JIRA_API_TOKEN=your_api_token \
  -e [email protected] \
  -- uv run --directory /path/to/mcp-jira python jira_mcp_server.py

或者，省略 -e 标志，并将凭据放入 mcp-jira 目录中的 .env 文件；load_dotenv() 会自动加载这些凭据。

测试

# Unit tests (no credentials needed)
uv sync --group dev
uv run pytest tests/ -v

架构

核心由两个文件组成：

• jira_mcp_server.py — 6 个 MCP 工具函数和 2 个提示词模板，每个都只是一个委托给客户端的薄封装
• jira_client.py — AsyncJiraClient，包含 JiraClientProtocol 接口、_CloudFormat/_ServerFormat 适配器、身份验证、连接池、速率限制、重试和响应转换

通过是否存在 JIRA_USER_EMAIL 来检测 Cloud 或 Server/DC。设计原因请参阅 docs/adr/0001-cloud-detection-via-email.md。