使用说明

Jira MCP服务器

生产就绪 模型上下文协议（MCP） 服务器，用于Jira与Claude Code、Cursor、Windsurf和其他MCP兼容的AI助手无缝集成。

🚀 特征

完成Jira集成：直接从IDE创建、更新、搜索和管理Jira票证
Git集成：自动将提交和分支链接到Jira票证
MCP兼容：适用于Claude Code、Cursor、Windsurf和其他MCP工具
自动更新：Git钩子在您提交代码时自动更新Jira票证
生产就绪：全面的错误处理、日志记录和配置
团队准备就绪：易于部署并与团队共享

📋 先决条件

Python 3.12或更高版本
紫外线包管理器
具有API访问权限的Jira帐户
Git（可选，用于自动提交跟踪）

安装 uv 如果你没有：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

🔧 安装

快速安装

macOS/Linux

# Clone or download this repository
cd jira_mcp_server

# Run installation script
chmod +x install.sh
./install.sh

Windows（PowerShell）

# Clone or download this repository
cd jira_mcp_server

# Run installation script
powershell -ExecutionPolicy Bypass -File install.ps1

手动安装

# Create virtual environment (uses .python-version automatically)
uv venv venv

# Activate
source venv/bin/activate        # macOS / Linux
# .\venv\Scripts\Activate.ps1  # Windows

# Install dependencies
uv pip install -r requirements.txt

# Copy environment template
cp .env.example .env  # macOS/Linux
# copy .env.example .env  # Windows

# Edit .env with your Jira credentials
nano .env         # macOS / Linux
# notepad .env   # Windows

⚙️ 配置

1.获取Jira API代币

首选https://id.atlassian.com/manage-profile/security/api-tokens
点击“创建API令牌”
复制令牌

2.配置环境变量

编辑 .env 文件：

# Your Jira instance URL
JIRA_URL=https://your-domain.atlassian.net

# Your Jira email
JIRA_EMAIL=your-email@company.com

# Your API token
JIRA_API_TOKEN=your_api_token_here

# Optional: Default project key
DEFAULT_PROJECT_KEY=PROJ

# Optional: Git repository path (defaults to current directory)
GIT_REPO_PATH=/path/to/your/repo

# Optional: Enable/disable auto-updates on git commits
JIRA_AUTO_UPDATE=true

🔌 IDE集成

Claude 代码

添加到您的Claude代码配置中：

{
  "mcpServers": {
    "jira": {
      "command": "/absolute/path/to/jira_mcp_server/venv/bin/python",
      "args": ["/absolute/path/to/jira_mcp_server/src/jira_mcp/server.py"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your_token_here"
      }
    }
  }
}

光标

打开设置（Ctrl+，）
转到“功能”>“MCP服务器”
添加配置：

{
  "jira": {
    "command": "/absolute/path/to/jira_mcp_server/venv/bin/python",
    "args": ["/absolute/path/to/jira_mcp_server/src/jira_mcp/server.py"]
  }
}

风浪（反重力）

添加到您的Windsurf MCP设置中：

{
  "mcpServers": {
    "jira": {
      "command": "/absolute/path/to/jira_mcp_server/venv/bin/python",
      "args": ["/absolute/path/to/jira_mcp_server/src/jira_mcp/server.py"]
    }
  }
}

📚 可用工具

1.创建Jira票证

Create a new Jira ticket

参数：

project_key （必填）：项目密钥（例如“PROJ”）
summary （必填）：门票标题
description （必填）：详细说明
issue_type：故事、任务、Bug等。（默认值：任务）
priority：最高、高、中、低、最低
assignee：要分配的用户名
labels：标签数组

例子：

Create a Jira ticket in project PROJ with summary "Implement user authentication" 
and description "Add JWT-based authentication system with refresh tokens"

2.添加评论

Add a comment to an existing Jira ticket

参数：

issue_key （必填）：票钥匙（例如“PROJ-123”）
comment （必填）：评论文本

例子：

Add a comment to PROJ-123: "Completed initial implementation, ready for review"

3.更新工单

Update an existing Jira ticket's fields

参数：

issue_key （必填）：票钥匙
summary：新标题
description：新描述
status：新状态
priority：新优先级
assignee：新受让人

例子：

Update PROJ-123 to status "In Progress" and assign to john.doe

4.获取门票详细信息

Get comprehensive details of a Jira ticket

参数：

issue_key （必填）：票钥匙

例子：

Get details of ticket PROJ-123

5.搜索门票

Search for tickets using JQL (Jira Query Language)

参数：

jql （必填）：JQL查询字符串
max_results：最大结果（默认值：50）

例子：

Search for tickets: "project = PROJ AND status = 'In Progress' ORDER BY updated DESC"

6.链接Git提交

Link a git commit/branch to a Jira ticket

参数：

issue_key （必填）：票钥匙
branch_name：分支名称（如果未提供，则自动检测）
commit_hash：提交哈希（自动检测）
commit_message：提交消息（自动检测）
repository_url：存储库URL（自动检测）

例子：

Link the current git commit to PROJ-123

7.过渡票

Move a ticket to a new status

参数：

issue_key （必填）：票钥匙
transition （必填）：过渡名称

例子：

Transition PROJ-123 to "Done"

8.获取我的门票

Get tickets assigned to the current user

参数：

status：按状态筛选（可选）
max_results：最大结果（默认值：20）

例子：

Get my tickets that are in progress

🔄 Git集成

自动提交跟踪

安装git钩子后，服务器会自动：

从分支名称和提交消息中提取Jira票证密钥
链接提交到相应的Jira票证
添加带有提交信息的评论

分支命名约定：

git checkout -b feature/PROJ-123-user-authentication
git checkout -b bugfix/PROJ-456-fix-login-issue

提交消息约定：

git commit -m "PROJ-123: Implement JWT authentication"
git commit -m "Fix login bug PROJ-456"

安装Git挂钩

# From your git repository root
cp jira_mcp_server/hooks/post-commit .git/hooks/
chmod +x .git/hooks/post-commit

禁用自动更新

设定在 .env:

JIRA_AUTO_UPDATE=false

💡 使用示例

示例1：创建和跟踪特征开发

AI: I need to implement user authentication. Can you create a Jira ticket?

You: Yes, create a task in PROJ with summary "Implement user authentication" 
     and description "Add JWT-based auth with refresh tokens, OAuth2 support, 
     and password reset flow"

[Ticket PROJ-789 created]

You: Now create a branch for this work

[Creates branch: feature/PROJ-789-user-authentication]

You: [After working on the code]
     git commit -m "PROJ-789: Add JWT token generation and validation"

[Automatically adds commit info to PROJ-789]

示例2：日常站立助理

You: Show me my tickets in progress

[Lists all your in-progress tickets]

You: Add a comment to PROJ-123 about today's progress

[Adds comment with status update]

示例3：Bug跟踪

You: Search for all high priority bugs in PROJ

[Shows JQL search results]

You: Transition PROJ-456 to Done and add a comment explaining the fix

[Updates ticket status and adds comment]

🔍 测试

测试服务器

# Run server via uv (no manual activation needed)
uv run python src/jira_mcp/server.py

测试Jira连接

from jira_mcp.jira_client import JiraClient

client = JiraClient()
result = client.jira.current_user()
print(f"Connected as: {result}")

📝 日志记录

日志将写入：

jira_mcp.log （文件）
控制台输出

在中配置日志级别 .env:

LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

🚨 故障排除

“uv：找不到命令”

安装紫外线： curl -LsSf https://astral.sh/uv/install.sh | sh （macOS/Linux）
或者在Windows上： powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
安装后重新启动终端

“无法连接到Jira”

验证 JIRA_URL 正确（包括https://）
检查API令牌是否有效
确保电子邮件与您的Jira帐户匹配

“提交中找不到Jira密钥”

使用格式： PROJ-123 在分支名称或提交消息中
检查 JIRA_AUTO_UPDATE=true 在 .env

“在IDE中找不到工具”

配置后重新启动IDE
检查MCP服务器是否正在运行
验证配置中的路径是否为绝对路径

Git挂钩不工作

确保钩子具有执行权限： chmod +x .git/hooks/post-commit
检查钩子中的Python路径是否与您的安装相匹配
验证 .env 文件位于正确的位置

🔐 安全

永不承诺 .env 文件 到版本控制
安全存储API令牌
使用特定于环境的配置
定期轮换API令牌
查看git钩子输出中的敏感数据

📦 分配给团队

选项1:Git仓库

# Add to .gitignore
echo ".env" >> .gitignore
echo "venv/" >> .gitignore
echo "*.log" >> .gitignore

# Commit and push
git add .
git commit -m "Add Jira MCP Server"
git push

团队成员（macOS/Linux）：

git clone <repository-url>
cd jira_mcp_server
chmod +x install.sh && ./install.sh
# Edit .env with their credentials

团队成员（Windows）：

git clone <repository-url>
cd jira_mcp_server
powershell -ExecutionPolicy Bypass -File install.ps1
# Edit .env with their credentials

选项2：存档

# Create distribution archive
tar -czf jira-mcp-server.tar.gz \
  --exclude=venv \
  --exclude=.env \
  --exclude=*.log \
  --exclude=__pycache__ \
  jira_mcp_server/

团队成员（macOS/Linux）：

tar -xzf jira-mcp-server.tar.gz
cd jira_mcp_server
chmod +x install.sh && ./install.sh

团队成员（Windows）：

Expand-Archive jira-mcp-server.zip
cd jira_mcp_server
powershell -ExecutionPolicy Bypass -File install.ps1

🛠️ 发展

项目结构

jira_mcp_server/
├── src/
│   └── jira_mcp/
│       ├── __init__.py
│       ├── server.py          # Main MCP server
│       ├── jira_client.py     # Jira API client
│       └── git_integration.py # Git integration
├── hooks/
│   └── post-commit            # Git hook
├── .env.example               # Environment template
├── requirements.txt           # Dependencies
├── pyproject.toml             # Project configuration
├── .python-version            # Python version pin (3.12)
├── uv.lock                    # Locked dependency versions
├── install.sh                 # Installation script (macOS/Linux)
├── install.ps1                # Installation script (Windows)
└── README.md                  # This file

添加新功能

在中添加工具定义 server.py
实现逻辑 jira_client.py 或 git_integration.py
用示例更新README
彻底测试

📄 许可证

该项目专为内部团队使用而设计。根据组织的需要进行修改。

🤝 支持

对于问题或疑问：

检查故障排除部分
查看登录 jira_mcp.log
联系您团队的DevOps/平台团队

🎯 路线图

未来潜在的增强功能：

[]支持Jira服务器（内部部署）
[]用于实时更新的Webhook侦听器
[]批量操作
[]自定义字段支持
[]Sprint管理
[]时间跟踪集成
[]附件支持
[]高级JQL构建器

制作于❤️ 对于高效的开发团队

使用说明

Jira MCP服务器

🚀 特征

📋 先决条件

🔧 安装

快速安装

手动安装

⚙️ 配置

1.获取Jira API代币

2.配置环境变量

🔌 IDE集成

Claude 代码

光标

风浪（反重力）

📚 可用工具

1.创建Jira票证

2.添加评论

3.更新工单

4.获取门票详细信息

5.搜索门票

6.链接Git提交

7.过渡票

8.获取我的门票

🔄 Git集成

自动提交跟踪

安装Git挂钩

禁用自动更新

💡 使用示例

示例1：创建和跟踪特征开发

示例2：日常站立助理

示例3：Bug跟踪

🔍 测试

测试服务器

测试Jira连接

📝 日志记录

🚨 故障排除

“uv：找不到命令”

“无法连接到Jira”

“提交中找不到Jira密钥”

“在IDE中找不到工具”

Git挂钩不工作

🔐 安全

📦 分配给团队

选项1:Git仓库

选项2：存档

🛠️ 发展

项目结构

添加新功能

📄 许可证

🤝 支持

🎯 路线图

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

AI开发助手

必应中文搜索MCP服务器

PostgreSQL管理服务器

网页内容获取工具