AI导哈

Jira MCP服务器

企业级Jira MCP服务器，提供与Jira Cloud和Server/Data Center的全面集成，支持问题管理、项目导航和工作流自动化。

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

使用说明

⚠️ 重要免责声明

此代码是100%AI生成的。 使用风险自负。作者不保证其可靠性、安全性或适用于任何特定目的。在生产环境中使用之前，彻底审查和测试所有代码。

Jira MCP服务器

企业级模型上下文协议服务器，用于Jira云和服务器/数据中心的全面集成

一个生产就绪的MCP服务器，为AI助手提供对Jira Cloud和Jira服务器/数据中心的完全访问。支持与Jira的自然语言交互，以实现跨多个Jira工作区的问题管理、项目导航和工作流自动化。

✨ 特性

🏢 多工作区管理

  • 连接到多个Jira Cloud和服务器/数据中心实例
  • 支持云（API令牌）和服务器/数据中心（PAT）身份验证
  • 在工作空间之间无缝切换
  • 符合XDG的配置存储（~/.config/jira-mcp/）
  • 用于凭证管理的安全骨架文件工作流
  • 工作区验证和凭证管理

🎫 完整的问题生命周期

  • 搜索：基于JQL的强大问题搜索
  • CRUD操作：创建、阅读、更新和删除问题
  • 工作流管理：通过自定义工作流解决过渡问题
  • 作业：将问题分配给团队成员
  • 自定义字段：支持自定义字段操作

💬 协作功能

  • 评论：对问题注释进行完整的CRUD操作
  • 附件：上传、列出和删除文件附件
  • 链接：在问题之间创建关系（关系、块、重复等）
  • 子任务：创建和管理父子任务层次结构

📊 项目与发现

  • 列出所有可访问的项目
  • 获取详细的项目信息
  • 枚举可用的问题类型
  • 用户搜索作业

🚀 快速开始

先决条件

  • Python 3.12+ -现代Python功能所必需的
  • 诗歌 -依赖关系管理
  • Jira云或服务器/数据中心 -具有API访问权限的活动实例

安装

# Clone the repository
git clone [repository-url]
cd jira-mcp

# Install dependencies with Poetry
poetry install

# Start the MCP server
poetry run start-mcp

服务器使用STDIO传输运行，并通过模型上下文协议进行通信。

🔧 配置

配置位置

所有工作空间配置都存储在 ~/.config/jira-mcp/workspaces/ 拥有600个安全权限。

获取您的凭据

对于Jira Cloud：

  1. 导航到 大西洋API代币
  2. 点击 “创建API令牌”
  3. 标记它（例如，“AI助手MCP”）
  4. 立即复制令牌 （您将无法再次查看！）

对于Jira服务器/数据中心：

  1. 从Jira服务器实例生成个人访问令牌（PAT）
  2. 遵循组织的PAT创建流程
  3. 复制令牌以在配置中使用

添加工作区

推荐方法：骨架文件（安全）

创建可直接编辑的骨架配置文件：

# 1. Create skeleton file
jira_workspace(
    operation="create_workspace_skeleton",
    workspace_name="mycompany",
    auth_type="cloud"  # or "pat" for Server/Data Center
)

# 2. Edit the file at ~/.config/jira-mcp/workspaces/mycompany.json
# 3. Fill in your actual credentials
# 4. Remove the _instructions section
# 5. Restart the MCP server

替代方案：直接添加（程序化）

对于Jira Cloud：

jira_workspace(
    operation="add_workspace",
    workspace_name="mycompany",
    site_url="mycompany.atlassian.net",
    email="your.email@company.com",
    api_token="YOUR_API_TOKEN_HERE",
    auth_type="cloud"
)

对于Jira服务器/数据中心：

jira_workspace(
    operation="add_workspace",
    workspace_name="mycompany",
    site_url="jira.company.com",
    email="your.username",
    api_token="YOUR_PERSONAL_ACCESS_TOKEN",
    auth_type="pat"
)

服务器将：

  • 验证您的凭据
  • 测试连接
  • 将配置安全地存储在 ~/.config/jira-mcp/workspaces/mycompany.json
  • 将其设置为活动工作区（如果这是您的第一个）

管理工作区

# List all configured workspaces
jira_workspace(operation="list_workspaces")

# Switch to a different workspace
jira_workspace(operation="switch_workspace", workspace_name="otherworkspace")

# Get current workspace info
jira_workspace(operation="get_active_workspace")

# Validate workspace credentials
jira_workspace(operation="validate_workspace", workspace_name="mycompany")

# Remove a workspace
jira_workspace(operation="remove_workspace", workspace_name="oldworkspace")

📖 使用指南

🔍 搜索和阅读问题

使用JQL搜索：

jira_issues(
    operation="search",
    jql="project = ENG AND status = Open AND assignee = currentUser()",
    max_results=50
)

获取问题详细信息：

jira_issues(operation="read", issue_key="ENG-123")

获取可用转换：

jira_issues(operation="get_transitions", issue_key="ENG-123")

✏️ 创建和更新问题

创建新问题：

jira_issues(
    operation="create",
    project_key="ENG",
    issue_type="Task",
    summary="Implement new feature",
    description="Detailed description here",
    priority="High",
    labels=["backend", "urgent"],
    assignee="user@example.com"  # Optional
)

更新问题：

jira_issues(
    operation="update",
    issue_key="ENG-123",
    summary="Updated task title",
    description="Updated description",
    priority="Medium"
)

分配一个问题：

jira_issues(
    operation="assign",
    issue_key="ENG-123",
    assignee="user@example.com"
)

通过工作流进行转换：

jira_issues(
    operation="transition",
    issue_key="ENG-123",
    transition="In Progress",
    comment="Starting work on this task"  # Optional
)

💬 评论

列出评论：

jira_issues(operation="list_comments", issue_key="ENG-123")

添加评论：

jira_issues(
    operation="add_comment",
    issue_key="ENG-123",
    body="This is a comment from the AI assistant"
)

更新评论：

jira_issues(
    operation="update_comment",
    issue_key="ENG-123",
    comment_id="12345",
    body="Updated comment text"
)

删除评论：

jira_issues(
    operation="delete_comment",
    issue_key="ENG-123",
    comment_id="12345"
)

📎 附件

列出附件：

jira_issues(operation="list_attachments", issue_key="ENG-123")

上传文件：

jira_issues(
    operation="add_attachment",
    issue_key="ENG-123",
    filepath="/path/to/document.pdf"
)

删除附件：

jira_issues(
    operation="delete_attachment",
    attachment_id="67890"
)

🔗 问题链接和关系

创建链接：

jira_issues(
    operation="create_link",
    inward_issue="ENG-123",
    outward_issue="ENG-456",
    link_type="Blocks"  # or "Relates", "Duplicate", etc.
)

列表链接：

jira_issues(operation="list_links", issue_key="ENG-123")

删除链接：

jira_issues(operation="delete_link", link_id="11111")

📋 子任务

创建子任务：

jira_issues(
    operation="create_subtask",
    parent_key="ENG-123",
    summary="Subtask: Implement unit tests",
    description="Write comprehensive tests",
    assignee="developer@example.com"  # Optional
)

列出子任务：

jira_issues(operation="list_subtasks", issue_key="ENG-123")

📊 项目

列出所有项目：

jira_projects(operation="list")

获取项目详细信息：

jira_projects(operation="get", project_key="ENG")

获取项目的问题类型：

jira_projects(operation="get_issue_types", project_key="ENG")

👥 用户

获取当前用户：

jira_workspace(operation="get_current_user")

搜索用户：

jira_workspace(
    operation="search_users",
    query="john",
    max_results=10
)

🏗️ 建筑

项目结构

jira-mcp/
├── jira_mcp/
│   ├── __init__.py           # Package initialization
│   ├── __main__.py           # Entry point for module execution
│   ├── server.py             # Main server & STDIO transport
│   ├── mcp_server.py         # MCP tool registration & routing
│   ├── config.py             # Configuration management
│   ├── workspace_manager.py  # Multi-workspace handling
│   ├── jira_client.py        # Jira API client wrapper
│   └── issue_manager.py      # Issue operations (CRUD, comments, etc.)
├── docs/                     # Documentation
│   └── implementation.md     # Implementation specification
├── pyproject.toml           # Poetry dependencies & config
├── poetry.lock              # Locked dependencies
└── README.md                # This file

~/.config/jira-mcp/          # XDG config directory (created automatically)
├── workspaces/              # Workspace configurations
│   ├── workspace1.json
│   └── workspace2.json
└── active_workspace         # Currently active workspace

MCP工具

服务器暴露 3个MCP工具 随着 总共32次操作:

  1. jira_workspace （10项操作）-工作空间管理（包括 create_workspace_skeleton)
  2. jira_projects （3项操作）-项目发现
  3. jira_issues （19项操作）-完成问题管理

技术栈

  • Python 3.12+ -带有类型提示的现代Python
  • MCP-SDK -模型上下文协议实现
  • Jira Python库 -Jira API官方客户
  • 诗歌 -依赖管理和打包
  • STDIO传输 -标准MCP通信协议

🧪 发展

代码质量

# Run pylint (target: 10.00/10)
poetry run pylint jira_mcp/

# Type checking with mypy
poetry run mypy jira_mcp/

# Security analysis
poetry run bandit -r jira_mcp/

# Dependency security audit
poetry run pip-audit

测试

# Run test suite
poetry run pytest

# With coverage
poetry run pytest --cov=jira_mcp

项目标准

  • 代码质量：皮林得分维持在10.00/10
  • 类型安全：带有mypy验证的完整类型提示
  • 安全：土匪安全扫描，代码中没有秘密
  • 文档：所有功能的综合文档字符串
  • 错误处理：在所有层进行适当的异常处理

📊 统计

  • 总运营量：3个MCP工具共32个
  • 代码行：~4600生产代码
  • 代码质量：10.00/10皮林分
  • 测试覆盖率：手动MCP集成测试
  • Python版本: 3.12+
  • 支持的平台：Jira Cloud+Jira服务器/数据中心

🔒 安全

最佳实践

  • API令牌：存储在 ~/.config/jira-mcp/workspaces/ 拥有600个权限
  • XDG合规性：配置遵循XDG基本目录规范
  • 代码中没有秘密：从配置文件加载的所有凭据
  • 身份验证类型：同时支持云（API令牌）和服务器/数据中心（PAT）
  • 输入验证：在API调用之前验证的所有参数
  • 错误处理：没有敏感数据的安全错误消息
  • 骨架工作流：建议避免通过工具调用传递凭据的方法

工作空间存储

工作区配置存储在 ~/.config/jira-mcp/workspaces/*.json 具有受限权限：

Jira Cloud：

{
  "name": "mycompany",
  "site_url": "https://mycompany.atlassian.net",
  "email": "user@company.com",
  "api_token": "YOUR_API_TOKEN",
  "auth_type": "cloud",
  "created": "2026-02-05T07:20:00.000000",
  "last_validated": null
}

Jira服务器/数据中心：

{
  "name": "myserver",
  "site_url": "https://jira.company.com",
  "email": "username",
  "api_token": "YOUR_PERSONAL_ACCESS_TOKEN",
  "auth_type": "pat",
  "created": "2026-02-05T07:20:00.000000",
  "last_validated": null
}

安全说明:

  • 文件会自动创建，具有600个权限（仅限所有者读/写）
  • 配置目录在用户的主目录中，而不是在项目存储库中
  • 使用 create_workspace_skeleton 避免通过工具调用传递凭据的操作

🐛 故障排除

常见问题

“无活动工作区”错误：

# Add a workspace first
jira_workspace(operation="add_workspace", ...)

工作区未加载：

  1. 检查文件是否存在： ls ~/.config/jira-mcp/workspaces/
  2. 检查文件权限： ls -la ~/.config/jira-mcp/workspaces/
  3. 验证JSON语法： cat ~/.config/jira-mcp/workspaces/myserver.json | python -m json.tool
  4. 重新启动MCP服务器（关闭并重新打开AI助手）

“身份验证失败”错误：

  • 验证您的API令牌是否正确
  • 检查您的电子邮件是否与您的Atlassian帐户匹配
  • 确保站点URL正确（例如。， company.atlassian.net)
  • 验证auth_type是否与Jira实例匹配（云与服务器）
  • 对于PAT：确保令牌有效且未过期
  • 测试连接： jira_workspace(operation="validate_workspace", workspace_name="myserver")

“无效JQL”错误：

  • 首先在Jira的web界面中测试JQL
  • 确保字段名称正确（区分大小写）
  • 检查值的引用是否正确

文件附件上传失败：

  • 验证文件路径是否存在并且可读
  • 检查文件大小限制（Jira默认为10MB）
  • 确保您在项目中具有附件权限

多个工作区：

  • 一次只能有一个工作区处于活动状态
  • 使用 switch_workspace 在工作区之间切换
  • 活动工作区存储在 ~/.config/jira-mcp/active_workspace

🤝 贡献

欢迎投稿！拜托：

  1. 克隆该仓库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add amazing feature')
  4. 保持10.00/10皮林分
  5. 添加新功能的测试
  6. 推到分支(git push origin feature/amazing-feature)
  7. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

🙏 致谢

📞 支持

对于问题、疑问或贡献：

  • 在GitHub上打开一个问题
  • 检查 docs/ 详细文档目录
  • 审查 docs/implementation.md 了解技术细节

由...制作❤️ 用于AI驱动的Jira管理

相关 MCP