使用说明

MCP-Jira

Jira Cloud的Python MCP服务器（REST API v3），采用FastMCP和atlassian-python-api构建。它提供了问题管理工具（创建、读取、更新、删除、搜索、状态转换、评论、附件），以便AI客户端（例如Cursor）能够安全地自动化Jira工作流。

要求

Python 3.10及以上版本
紫外线pipx install uv 或者遵循紫外线文档（指南）
带有API令牌的Jira云账户
- 在 https://id.atlassian.com/manage-profile/security/api-tokens 创建API令牌

安装（可编辑版本）

uv pip install -e .

Docker 使用（HTTP/SSE 传输）

MCP服务器运行在一个使用HTTP/SSE传输的Docker容器中，允许一个长运行的容器处理多个游标连接。

快速入门

创建环境文件：

cp .env.example .env
# Edit .env with your Jira credentials

构建并启动容器：

docker-compose up -d --build

配置光标 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "jira": {
      "url": "http://localhost:9001/sse"
    }
  }
}

重启光标 - Jira MCP 服务器现在应该可以使用了！

手动 Docker 命令

构建镜像：

docker build -t mcp-jira:latest .

使用 docker-compose 运行：

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

直接使用 Docker 运行：

docker run -d \
  --name mcp-jira \
  -p 9001:9001 \
  -e JIRA_URL=https://your-domain.atlassian.net \
  -e JIRA_EMAIL=your.email@example.com \
  -e JIRA_API_TOKEN=your_api_token \
  -e JIRA_DEFAULT_PROJECT=PROJ \
  -e MCP_TRANSPORT=sse \
  mcp-jira:latest

健康检查

验证服务器是否正在运行：

curl http://localhost:9001/sse

集装箱管理

# Check if running
docker ps | grep mcp-jira

# View logs
docker logs mcp-jira

# Restart
docker restart mcp-jira

# Stop and remove
docker stop mcp-jira
docker rm mcp-jira

HTTP/SSE传输的优势

单个集装箱一个长期运行的容器处理所有请求
多个连接Cursor 可以连接/重新连接而无需创建新容器
更好的性能每个请求无需容器启动开销
更容易的调试查看日志使用 docker logs
健康监测内置健康检查

多项目设置

如果你需要使用不同的凭据在多个Jira实例上工作，你可以运行多个容器：

设置：

创建特定于项目的环境文件：

cp .env.project1.example .env.project1
cp .env.project2.example .env.project2
# Edit each with the appropriate credentials

启动两个容器：

docker compose -f docker-compose.project1.yml up -d
docker compose -f docker-compose.project2.yml up -d

在两个服务器上配置Cursor：

{
  "mcpServers": {
    "jira-project1": {
      "url": "http://localhost:9001/sse"
    },
    "jira-project2": {
      "url": "http://localhost:9002/sse"
    }
  }
}

管理：

# Start all projects
docker compose -f docker-compose.project1.yml up -d
docker compose -f docker-compose.project2.yml up -d

# Stop specific project
docker compose -f docker-compose.project1.yml down

# View logs for specific project
docker compose -f docker-compose.project1.yml logs -f

配置

环境变量：

JIRA_URL：您的Jira云实例URL（例如。， https://your-company.atlassian.net)
JIRA_EMAIL：您的Jira账户邮箱
JIRA_API_TOKEN：来自https://id.atlassian.com/manage-profile/security/api-tokens的API令牌
JIRA_DEFAULT_PROJECT: 默认项目密钥（可选，但方便）
FASTMCP_LOG_LEVEL: DEBUG|INFO|...（可选）

运行（标准输入输出服务器）

JIRA_URL='https://your-domain.atlassian.net' \
JIRA_EMAIL='your.email@example.com' \
JIRA_API_TOKEN='your_api_token' \
JIRA_DEFAULT_PROJECT='PROJ' \
uv run mcp-jira

服务器使用标准输入输出，并且在客户端连接之前只打印少量信息。

使用MCP Inspector进行调试

通过（某种方式）暴露一个FastMCP实例 src/app.py 并启动检查器：

JIRA_URL='https://your-domain.atlassian.net' \
JIRA_EMAIL='your.email@example.com' \
JIRA_API_TOKEN='your_api_token' \
JIRA_DEFAULT_PROJECT='PROJ' \
uv run --with mcp mcp dev src/app.py --with-editable .

打开打印出的URL，并调用工具如 health 并且 getProjects。

与光标配合使用（原生/开发）

选项1：Docker（推荐用于生产环境）

见 Docker 使用方法上面的部分。

选项2：直接紫外线（用于开发）

如果Cursor在同一个Ubuntu WSL2环境中运行，建议使用绝对路径 uv 并添加可编辑的源代码以确保使用本地树：

{
  "mcpServers": {
    "jira": {
      "command": "/home/nemanja/.local/bin/uv",
      "args": ["run", "--with-editable", "/home/nemanja/projects/mcp/mcp-jira", "mcp-jira"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your.email@example.com",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_DEFAULT_PROJECT": "PROJ",
        "FASTMCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

选项3：WSL桥（Windows）

如果 Cursor 在 Windows 上运行（不在 WSL 中），请通过以下方式连接到 WSL：

{
  "mcpServers": {
    "jira": {
      "command": "wsl",
      "args": [
        "bash", "-lc",
        "cd /home/<user>/projects/mcp/mcp-jira && JIRA_URL='https://your-domain.atlassian.net' JIRA_EMAIL='your.email@example.com' JIRA_API_TOKEN='your_api_token' JIRA_DEFAULT_PROJECT='PROJ' /home/<user>/.local/bin/uv run mcp-jira"
      ]
    }
  }
}

工具（高级）

健康与配置：

health - 验证配置和Jira连接性

发行操作：

getIssue - 获取有关某个问题的详细信息
createIssue - 创建一个新问题，包含摘要、描述、类型、优先级、负责人、标签
updateIssue - 更新问题字段（摘要、描述、优先级、负责人、标签）
searchIssues - 使用JQL（Jira查询语言）搜索问题

过渡与工作流程：

getTransitions - 获取问题的可用状态转换
transitionIssue - 将问题移动到不同的状态（例如，待办事项 → 进行中）

评论：

addComment - 在问题上添加评论
getComments - 获取某个问题的所有评论

附件：

addAttachment - 向问题添加文件附件（以base64编码）

项目与元数据：

getProjects - 列出所有可访问的项目
getProject - 获取特定项目的详细信息
getIssueTypes - 获取项目的可用问题类型

所有工具均返回与MCP兼容的响应（带有成功/错误状态的JSON）。

常见使用场景

创建一个问题：

Use the createIssue tool:
- project: "PROJ"
- summary: "Implement new feature"
- description: "Detailed description here"
- issue_type: "Task"

搜索问题：

Use the searchIssues tool with JQL:
- jql: "project = PROJ AND status = 'In Progress'"
- max_results: 10

转换一个话题：

1. First, use getTransitions to see available transitions
2. Then use transitionIssue with the transition ID

添加评论：

Use the addComment tool:
- issue_key: "PROJ-123"
- comment: "Work in progress, will update soon"

故障排除

客户端中没有工具：

确保命令在您的环境中确实能够启动（使用绝对路径到 uv （有帮助）
添加 FASTMCP_LOG_LEVEL=DEBUG 查看详细日志
检查所有必需的环境变量是否已设置

401/403错误：

验证API令牌是否正确且未过期
检查您的Jira账户是否具有适当的权限
确保 JIRA_URL 正确（包含 https://，且不以斜杠结尾）

连接错误：

验证从您的网络可以访问 JIRA_URL
检查是否需要连接VPN以访问公司内部的Jira实例
测试连接性： curl https://your-domain.atlassian.net

Docker 容器无法启动：

检查日志： docker logs mcp-jira
验证 .env 文件是否存在且包含正确的值
确保端口9001未被占用

检测器无法连接：

确保代理健康状况良好 http://localhost:6277/health 回报；收益 { "status": "ok" }
如果从Windows桥接到WSL（Windows Subsystem for Linux），请在WSL中启用本地主机转发

安全

将API令牌视为机密。切勿将其提交到版本控制系统中。
使用 .env 用于本地开发的文件（这些文件在.gitignore中被忽略）
对于生产环境，使用Docker密钥或环境变量注入
如果API令牌暴露，需进行轮换
API令牌位于：https://id.atlassian.com/manage-profile/security/api-tokens

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件