使用说明

Jira MCP服务器

FastMCP服务器，使AI助手能够通过令牌身份验证与自托管的Jira实例进行交互。

特性

MVP（v0.1.0）

✅ 问题管理：使用自动自定义字段验证创建、读取和更新Jira问题
✅ 智能自定义字段处理：自动发现和验证特定于项目的自定义字段
✅ 架构缓存：智能缓存将API调用减少80%+
✅ 健康检查：验证连接和身份验证
✅ 图式反思：调试工具，用于探索可用字段

v0.2.0版本

✅ 强大的搜索：按项目、受让人、状态、优先级、标签和日期范围搜索问题
✅ JQL支持：直接执行原始JQL查询，并完全支持Jira查询语言

v0.3.0

✅ 自定义筛选器：通过完整的CRUD操作保存和重用复杂的搜索查询
✅ 筛选器执行：运行支持分页的已保存筛选器

v0.4.0

✅ 工作流转换：通过工作流状态移动问题
✅ 过渡发现：获取任何问题的可用转换

v0.5.0-最新版本

✅ 评论管理：问题注释的完整CRUD操作（添加、列表、更新、删除）
✅ 评论权限：更新/删除的作者和管理员权限控制
✅ Jira标记支持：完全支持评论中的Jira文本格式

需求

Python 3.8或更高版本
自托管Jira实例（7.0+版本）
具有适当权限的Jira API令牌

安装

pip install fastmcp-jira-server

快速开始

获取Jira API代币:
- 登录您的Jira实例
- 转到个人资料→ 个人访问令牌
- 创建新令牌并复制值

配置环境变量:

export JIRA_MCP_URL="https://jira.yourcompany.com"
export JIRA_MCP_TOKEN="your-api-token-here"

或者创建一个 .env 文件（参见 .env.example):

JIRA_MCP_URL=https://jira.yourcompany.com
JIRA_MCP_TOKEN=your-api-token-here

运行服务器:
```
fastmcp-jira-server
```
验证连接:

使用 jira_health_check 通过MCP客户端验证连接。

使用AI助手

FastMCP Jira服务器可以与任何兼容MCP的AI助手一起使用。以下是常用工具的配置说明。

克劳德桌面

添加到您的Claude Desktop配置文件中：

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

{
  "mcpServers": {
    "jira": {
      "command": "fastmcp-jira-server",
      "env": {
        "JIRA_MCP_URL": "https://jira.yourcompany.com",
        "JIRA_MCP_TOKEN": "your-api-token-here"
      }
    }
  }
}

更新配置后，重新启动Claude Desktop。Jira工具将出现在MCP工具菜单中。

Cline（VS代码扩展）

添加到您的Cline MCP设置(~/.cline/mcp_settings.json):

{
  "mcpServers": {
    "jira": {
      "command": "fastmcp-jira-server",
      "env": {
        "JIRA_MCP_URL": "https://jira.yourcompany.com",
        "JIRA_MCP_TOKEN": "your-api-token-here"
      }
    }
  }
}

更新配置后重新启动VS Code。

帆板运动

添加到您的Windsurf配置中：

macOS/Linux: ~/.windsurf/mcp_config.json 视窗: %USERPROFILE%\.windsurf\mcp_config.json

{
  "mcpServers": {
    "jira": {
      "command": "fastmcp-jira-server",
      "env": {
        "JIRA_MCP_URL": "https://jira.yourcompany.com",
        "JIRA_MCP_TOKEN": "your-api-token-here"
      }
    }
  }
}

重新启动Windsurf以加载新配置。

光标

添加到光标MCP设置中：

macOS: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json 视窗: %APPDATA%\Cursor\User\globalStorage\mcp.json Linux: ~/.config/Cursor/User/globalStorage/mcp.json

{
  "mcpServers": {
    "jira": {
      "command": "fastmcp-jira-server",
      "env": {
        "JIRA_MCP_URL": "https://jira.yourcompany.com",
        "JIRA_MCP_TOKEN": "your-api-token-here"
      }
    }
  }
}

更新配置后重新启动Cursor。

GitHub副本（VS代码）

需求：VS Code 1.99+和启用MCP策略的GitHub Copilot

创建 .vscode/mcp.json 在项目根目录中：

{
  "inputs": [
    {
      "type": "promptString"
    }
  ],
  "servers": {
    "jira": {
      "command": "fastmcp-jira-server"
    }
  }
}

环境变量：在启动VS Code之前，在shell中设置这些：

export JIRA_MCP_URL="https://jira.yourcompany.com"
export JIRA_MCP_TOKEN="your-api-token-here"
code .

或者添加到您的VS代码中 settings.json:

{
  "terminal.integrated.env.osx": {
    "JIRA_MCP_URL": "https://jira.yourcompany.com",
    "JIRA_MCP_TOKEN": "your-api-token-here"
  },
  "terminal.integrated.env.linux": {
    "JIRA_MCP_URL": "https://jira.yourcompany.com",
    "JIRA_MCP_TOKEN": "your-api-token-here"
  },
  "terminal.integrated.env.windows": {
    "JIRA_MCP_URL": "https://jira.yourcompany.com",
    "JIRA_MCP_TOKEN": "your-api-token-here"
  }
}

保存后 .vscode/mcp.json，单击文件顶部出现的“开始”按钮。通过Copilot Chat in访问Jira工具代理通过单击工具图标进入模式。

验证

配置后，通过询问您的AI助手来测试连接：

“使用jira_health_check工具验证jira连接”

您应该看到一个确认连接状态和服务器版本的响应。

用法示例

检查健康状况

# Verify connectivity and authentication
jira_health_check()
# Returns: {"connected": true, "server_version": "8.20.0", "base_url": "https://jira.yourcompany.com"}

创建问题

# Basic issue creation
jira_issue_create(
    project="PROJ",
    summary="Login page shows 404 error",
    issue_type="Bug",
    priority="High",
    description="Users are seeing 404 errors when accessing /login"
)

# With custom fields (automatically validated against project schema)
jira_issue_create(
    project="PROJ",
    summary="Add user authentication",
    issue_type="Story",
    custom_fields={
        "customfield_10001": 8,  # Story Points
        "customfield_10002": "Backend",  # Component
    }
)

更新问题

# Update specific fields
jira_issue_update(
    issue_key="PROJ-123",
    summary="Updated: Login page shows 404 error",
    priority="Critical",
    assignee="john.doe"
)

# Update custom fields
jira_issue_update(
    issue_key="PROJ-123",
    custom_fields={
        "customfield_10001": 13  # Update story points
    }
)

获取问题详细信息

# Retrieve full issue details including all custom fields
jira_issue_get(issue_key="PROJ-123")

发现项目架构

# Useful for finding custom field IDs and allowed values
jira_project_get_schema(
    project="PROJ",
    issue_type="Bug"
)
# Returns all available fields, their types, and validation rules

搜索问题

# Search by project
jira_search_issues(project="PROJ")

# Search with multiple criteria
jira_search_issues(
    project="PROJ",
    status="Open",
    assignee="currentUser()",
    priority="High",
    max_results=10
)

# Search by date range
jira_search_issues(
    project="PROJ",
    created_after="2025-01-01",
    created_before="2025-12-31"
)

# Search by labels
jira_search_issues(
    project="PROJ",
    labels=["backend", "urgent"]
)

执行JQL查询

# Simple JQL query
jira_search_jql(jql="project = PROJ AND status = Open")

# Complex JQL with date functions and ordering
jira_search_jql(
    jql='project = PROJ AND created >= -7d AND assignee = currentUser() ORDER BY created DESC',
    max_results=20
)

# JQL with multiple conditions
jira_search_jql(
    jql='project = PROJ AND status IN ("Open", "In Progress") AND priority = High',
    max_results=50,
    start_at=0
)

管理已保存的筛选器

# Create a filter
filter_result = jira_filter_create(
    name="My Open Issues",
    jql="assignee = currentUser() AND status = Open",
    description="All my open issues"
)
filter_id = filter_result["id"]

# List all accessible filters
filters = jira_filter_list()

# Get filter details
filter_details = jira_filter_get(filter_id="10000")

# Execute a saved filter
results = jira_filter_execute(filter_id="10000", max_results=20)

# Update filter
jira_filter_update(
    filter_id="10000",
    jql="assignee = currentUser() AND status IN (Open, 'In Progress')"
)

# Delete filter
jira_filter_delete(filter_id="10000")

管理工作流转换

# Get available transitions for an issue
transitions = jira_workflow_get_transitions(issue_key="PROJ-123")
# Returns: {
#   "issue_key": "PROJ-123",
#   "transitions": [
#     {"id": "21", "name": "In Progress", "to_status": "In Progress", "has_screen": False, "fields": []},
#     {"id": "31", "name": "Done", "to_status": "Done", "has_screen": True, "fields": ["resolution"]}
#   ]
# }

# Simple transition (no fields required)
jira_workflow_transition(issue_key="PROJ-123", transition_id="21")

# Transition with required fields (e.g., resolution when closing)
jira_workflow_transition(
    issue_key="PROJ-123",
    transition_id="31",
    fields={"resolution": {"name": "Done"}}
)

# Transition with comment
jira_workflow_transition(
    issue_key="PROJ-123",
    transition_id="21",
    fields={"comment": [{"add": {"body": "Moving to in progress"}}]}
)

管理评论

# Add a comment to an issue
comment = jira_comment_add(
    issue_key="PROJ-123",
    body="This issue is ready for review"
)
# Returns: {
#   "id": "10001",
#   "body": "This issue is ready for review",
#   "author": {"displayName": "John Doe", "emailAddress": "john@example.com"},
#   "created": "2025-01-15T10:00:00.000+0000"
# }

# Add comment with Jira markup
jira_comment_add(
    issue_key="PROJ-123",
    body="Status update:\n* Task 1: *Done*\n* Task 2: _In progress_\n* Task 3: {{Not started}}"
)

# List all comments on an issue
comments = jira_comment_list(issue_key="PROJ-123")
# Returns: {
#   "comments": [
#     {
#       "id": "10001",
#       "body": "First comment",
#       "author": {"displayName": "John Doe"},
#       "created": "2025-01-15T10:00:00.000+0000"
#     },
#     {
#       "id": "10002",
#       "body": "Second comment",
#       "author": {"displayName": "Jane Smith"},
#       "created": "2025-01-15T11:00:00.000+0000"
#     }
#   ],
#   "total": 2
# }

# Update an existing comment
updated = jira_comment_update(
    issue_key="PROJ-123",
    comment_id="10001",
    body="Updated comment text"
)
# Returns: {
#   "id": "10001",
#   "body": "Updated comment text",
#   "author": {"displayName": "John Doe"},
#   "updated": "2025-01-15T12:00:00.000+0000"
# }

# Delete a comment
result = jira_comment_delete(issue_key="PROJ-123", comment_id="10001")
# Returns: {
#   "success": true,
#   "message": "Comment 10001 deleted successfully",
#   "issue_key": "PROJ-123",
#   "comment_id": "10001"
# }

配置

环境变量：

JIRA_MCP_URL （必填）：您的Jira实例URL
JIRA_MCP_TOKEN （必需）：API身份验证令牌
JIRA_MCP_CACHE_TTL （可选，默认值：3600）：架构缓存TTL（秒）
JIRA_MCP_TIMEOUT （可选，默认值：30）：HTTP请求超时（秒）
JIRA_MCP_VERIFY_SSL （可选，默认值：true）：验证SSL证书

SSL证书验证

默认情况下，服务器验证SSL证书。对于使用自签名证书进行测试，您可以禁用SSL验证：

export JIRA_MCP_VERIFY_SSL="false"

或者在您的AI助手配置中：

{
  "mcpServers": {
    "jira": {
      "command": "fastmcp-jira-server",
      "env": {
        "JIRA_MCP_URL": "https://jira.yourcompany.com",
        "JIRA_MCP_TOKEN": "your-api-token-here",
        "JIRA_MCP_VERIFY_SSL": "false"
      }
    }
  }
}

安全警告：禁用SSL验证只能用于使用自签名证书进行测试或内部开发。永远不要在生产环境中使用它，因为它会使您的连接容易受到中间人攻击。

发展

设置

git clone https://github.com/yourusername/jira-mcp-server.git
cd jira-mcp-server
pip install -e ".[dev]"

运行测试

pytest

附报道：

pytest --cov=src/jira_mcp_server --cov-report=html

类型检查

mypy src/

代码格式化和Linting

# Check and auto-fix
ruff check src/ tests/ --fix

# Format code
ruff format src/ tests/

建筑

FastMCP：MCP服务器框架
httpx：Jira REST API的HTTP客户端
派丹蒂克：数据验证和设置管理
内存缓存：基于TTL的架构缓存（默认1小时）

MCP工具

MVP（v0.1.0）

问题管理

jira_issue_create -使用自动自定义字段验证创建新问题
jira_issue_update -更新现有问题（仅更新提供的字段）
jira_issue_get -获取完整的问题详细信息，包括所有自定义字段

公用事业

jira_health_check -验证连接和身份验证状态
jira_project_get_schema -获取用于调试的项目架构（显示所有可用字段、类型和验证规则）

v0.2.0版本

搜索

jira_search_issues -使用多个条件搜索（项目、受让人、状态、优先级、标签、日期范围）
jira_search_jql -直接执行JQL查询，完全支持Jira查询语言

v0.3.0

过滤器

jira_filter_create -使用名称和JQL查询创建自定义筛选器
jira_filter_list -列出所有可访问的筛选器
jira_filter_get -按ID获取筛选器详细信息
jira_filter_execute -运行支持分页的已保存筛选器
jira_filter_update -更新筛选条件（名称、JQL、描述）
jira_filter_delete -删除筛选器（仅限所有者）

v0.4.0

工作流

jira_workflow_get_transitions -获取问题的可用转换
jira_workflow_transition -通过工作流解决过渡问题

v0.5.0-最新版本

评论（完整CRUD）

jira_comment_add -向问题添加评论（支持Jira标记）
jira_comment_list -列出关于一个问题的所有评论，包括作者和时间戳信息
jira_comment_update -更新现有评论（仅限作者或管理员）
jira_comment_delete -删除评论（仅限作者或管理员）

故障排除

请参阅 quickstart.md中的故障排除部分常见问题和解决方案。

贡献

欢迎投稿！请阅读贡献.md 发展指南。

许可证

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

支持

问题: GitHub问题
文档: 全部文件

使用说明

Jira MCP服务器

特性

MVP（v0.1.0）

v0.2.0版本

v0.3.0

v0.4.0

v0.5.0-最新版本

需求

安装

快速开始

使用AI助手

克劳德桌面

Cline（VS代码扩展）

帆板运动

光标

GitHub副本（VS代码）

验证

用法示例

检查健康状况

创建问题

更新问题

获取问题详细信息

发现项目架构

搜索问题

执行JQL查询

管理已保存的筛选器

管理工作流转换

管理评论

配置

SSL证书验证

发展

设置

运行测试

类型检查

代码格式化和Linting

建筑

MCP工具

MVP（v0.1.0）

问题管理

公用事业

v0.2.0版本

搜索

v0.3.0

过滤器

v0.4.0

工作流

v0.5.0-最新版本

评论（完整CRUD）

故障排除

贡献

许可证

支持

相关 MCP

Unity MCP AI游戏开发工具

模型上下文协议服务器

SearXNG与n8n集成服务器

AI模型协调服务

智能任务管理系统

LLM交互工具