AI导哈

Jira集成服务器

一个用于Jira集成的干净可靠的Model Context Protocol服务器，支持Claude Desktop和其他MCP客户端。

  • by Positronic-AI
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Positronic-AI/jira-mcp

使用说明

Jira MCP服务器

干净、可靠 模型上下文协议 用于Jira集成的服务器，专为与Claude Desktop和其他MCP客户端一起使用而设计。

为什么存在

现有的Jira MCP服务器存在质量问题：

  • Pydantic依赖冲突
  • 不推荐使用API（v2而不是v3）
  • 错误处理不当
  • 不可靠的连接

该实施侧重于：

  • ✅ 现代Jira REST API v3
  • ✅ 最小、稳定的依赖关系
  • ✅ 正确的错误处理
  • ✅ 多实例支持
  • ✅ 全程类型安全

特性

核心业务

  • 🔍 搜索问题 JQL（Jira查询语言）
  • 📄 获取问题详细信息 具有完整的字段信息
  • ➕ 创建问题 带有描述、标签、父级/史诗级链接和自定义字段
  • ✏️ 更新问题 （摘要、描述、标签等）
  • 💬 添加注释 到问题
  • 🔄 过渡问题 状态之间
  • 📋 列出项目 用户可访问

高级功能

  • 🔗 链接问题 与关系（关系、块、重复等）
  • 📊 Epic管理 -在史诗下创建任务并查询史诗儿童
  • 🔄 获取可用转换 过渡前问题
  • 👥 用户管理 -搜索用户并分配问题
  • 🎯 受让人控制 -将问题分配或取消分配给团队成员

多实例支持

同时连接到多个Jira实例：

  • 不同的组织
  • 个人和工作账户
  • 多个团队

快速开始

1.安装

选项A：从PyPI安装（推荐）

pip install jira-mcp-simple

备注：如果 jira-mcp 找不到命令，请将Python的bin添加到PATH：

export PATH="$HOME/.local/bin:$PATH"

选项B：从源代码安装

git clone https://github.com/Positronic-AI/jira-mcp.git
cd jira-mcp
pip install -e .

2.获取您的Jira API代币

  1. 首选https://id.atlassian.com/manage-profile/security/api-tokens
  2. 点击“创建API令牌”
  3. 给它起个名字（例如，“克劳德桌面MCP”）
  4. 复制令牌

3.测试连接

export JIRA_MYCOMPANY_URL="https://your-company.atlassian.net"
export JIRA_MYCOMPANY_EMAIL="your.email@company.com"
export JIRA_MYCOMPANY_TOKEN="your_api_token_here"

jira-mcp --test-connection mycompany

您应该看到：

✓ Connected successfully!
  User: Your Name (your@email.com)
  Account ID: 123abc...
  Accessible projects: N

4.配置克劳德桌面

编辑您的Claude Desktop配置文件：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp",
      "args": ["--instance", "mycompany"],
      "env": {
        "JIRA_MYCOMPANY_URL": "https://your-company.atlassian.net",
        "JIRA_MYCOMPANY_EMAIL": "your.email@company.com",
        "JIRA_MYCOMPANY_TOKEN": "your_api_token_here"
      }
    }
  }
}

备注：如果安装在虚拟环境中，请使用完整路径 jira-mcp例如。， /path/to/venv/bin/jira-mcp

5.重新启动克劳德桌面

完全退出并重新打开Claude Desktop。

6.测试一下！

在Claude中尝试以下命令：

List my Jira projects

Search for issues assigned to me

Show me PROJECT-123

Create a new task in PROJECT called "Test MCP integration"

使用示例

自然语言命令

配置后，您可以与Claude一起使用自然语言：

基本操作：

  • “查找MOBILE项目中所有打开的错误”
  • “显示分配给我的高优先级问题”
  • “创建一个关于修复登录页面的任务”
  • “在PROJ-42中添加一条评论，说明已部署修复程序”
  • “将PROJ-42移至进行中”
  • “更新PROJ-42的摘要，以包括更多细节”

高级操作：

  • “创建一个名为“用户身份验证系统”的新史诗”
  • “在史诗PROJ-10下创建一个任务来实现登录”
  • “使用‘块’关系将PROJ-42链接到PROJ-50”
  • “显示史诗PROJ-10下的所有任务”
  • “PROJ-42有哪些过渡？”
  • “搜索用户john.doe并将PROJ-42分配给他们”
  • “取消分配PROJ-42”

直接JQL查询

Search Jira with: project = PROJ AND status = "In Progress" ORDER BY priority DESC

多实例配置

要连接多个Jira实例，请执行以下操作：

{
  "mcpServers": {
    "jira-work": {
      "command": "jira-mcp",
      "args": ["--instance", "work"],
      "env": {
        "JIRA_WORK_URL": "https://company.atlassian.net",
        "JIRA_WORK_EMAIL": "you@company.com",
        "JIRA_WORK_TOKEN": "token1"
      }
    },
    "jira-personal": {
      "command": "jira-mcp",
      "args": ["--instance", "personal"],
      "env": {
        "JIRA_PERSONAL_URL": "https://personal.atlassian.net",
        "JIRA_PERSONAL_EMAIL": "you@personal.com",
        "JIRA_PERSONAL_TOKEN": "token2"
      }
    }
  }
}

Claude将根据上下文知道使用哪个实例。

建筑

jira-mcp/
├── server.py          # Main MCP server
├── jira_client.py     # Jira REST API v3 wrapper
├── config.py          # Configuration management
├── requirements.txt   # Python dependencies
└── examples/          # Configuration examples

关键设计决策

最小依赖性：只有基本的、稳定的软件包（mcp、httpx、pydantic、python-dotenv）

现代API：使用Jira REST API v3(/rest/api/3/search/jql)而不是弃用的v2

类型安全：完整的类型提示贯穿始终，以获得更好的IDE支持和更少的错误

错误处理：清除从Jira API传播的错误消息

多实例：多个Jira实例的基于环境的配置

可用工具

服务器公开了这些MCP工具：

核心工具

工具 说明
jira_search 使用带分页的JQL搜索问题
jira_get_issue 获取详细的问题信息
jira_create_issue 使用自定义字段和父链接创建新问题
jira_update_issue 更新现有问题字段
jira_add_comment 为问题添加评论
jira_transition_issue 更改问题状态
jira_list_projects 列出可访问的项目

高级工具

工具 说明
jira_link_issues 在问题之间建立关系（关系、块等）
jira_get_epic_issues 获取属于史诗的所有问题
jira_get_transitions 获取问题的可用转换
jira_search_users 按姓名或电子邮件搜索用户
jira_assign_issue 向用户分配或取消分配问题

故障排除

连接失败

  • 验证您的API令牌是否正确
  • 检查Jira URL是否没有尾随斜线
  • 确保您的电子邮件与Atlassian帐户匹配
  • 测试： jira-mcp --test-connection <instance>

Claude Desktop看不到服务器

  • 验证JSON配置是否有效
  • 使用绝对路径（不 ~/ 或相对）
  • 完全重新启动克劳德桌面
  • 检查Claude Desktop日志是否有错误

“找不到模块”错误

  • 确保 jira-mcp-simple 已安装： pip install jira-mcp-simple
  • 如果使用虚拟环境，请确保其已激活或使用完整路径

“无法设置字段”错误

  • 并非所有项目上的所有字段都可用
  • 检查项目的问题类型屏幕配置
  • 常见问题： priority 字段不在屏幕上（使其可选）

贡献

欢迎投稿！看 贡献.md 作为指导方针。

我们特别希望得到帮助的领域：

  • 单元和集成测试
  • Jira数据中心支持
  • 附件处理
  • Sprint/董事会运营
  • 自定义字段改进

发展

# Clone and setup
git clone https://github.com/Positronic-AI/jira-mcp.git
cd jira-mcp
pip install -e ".[dev]"

# Test connection
export JIRA_TEST_URL="https://test.atlassian.net"
export JIRA_TEST_EMAIL="test@example.com"
export JIRA_TEST_TOKEN="test_token"
jira-mcp --test-connection test

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

支持

备注：这是一个独立的项目，与Atlassian或Anthropic无关。

相关 MCP