使用说明

MCP Jira

Jira的模型上下文协议（MCP）服务器。此集成支持Jira Cloud和服务器/数据中心部署。

示例用法

让你的AI助手：

📝 Jira自动更新 -“从我们的会议记录中更新Jira”
🐛 智能Jira问题过滤 -“显示上周PROJ项目中的紧急错误”
🔍 AI驱动的Jira搜索 -“查找分配给我的本周到期的所有问题”

功能演示

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

兼容性

产品	部署类型	支持状态
Jira	云	✅ 完全支持
Jira	服务器/数据中心	✅ 支持（8.14+版本）

快速入门指南

🔐 1.身份验证设置

MCP Atlassian Jira支持三种身份验证方法：

A.API令牌认证（云）- 推荐

首选https://id.atlassian.com/manage-profile/security/api-tokens
点击 创建API令牌，命名它
立即复制令牌

B.个人访问令牌（服务器/数据中心）

转到您的个人资料（头像）→ 个人资料 → 个人访问令牌
点击 创建令牌，命名它，设置过期时间
立即复制令牌

C.OAuth 2.0认证（云）- 高级

[！注意] OAuth 2.0的设置更复杂，但提供了增强的安全功能。对于大多数用户来说，API令牌身份验证（方法A）更加简单和充分。

首选 Atlassian开发人员控制台
创建“OAuth 2.0（3LO）集成”应用程序
配置权限 Jira的（范围）
集 回调URL （例如。， http://localhost:8080/callback)

运行安装向导：

docker run --rm -i \
  -p 8080:8080 \
  -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
  ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

按照提示进行操作 Client ID, Secret, URI，以及 Scope
完成浏览器授权
将获得的凭据添加到 .env 或IDE配置：
- ATLASSIAN_OAUTH_CLOUD_ID （来自向导）
- ATLASSIAN_OAUTH_CLIENT_ID
- ATLASSIAN_OAUTH_CLIENT_SECRET
- ATLASSIAN_OAUTH_REDIRECT_URI
- ATLASSIAN_OAUTH_SCOPE

[！重要] 对于上述标准OAuth流程，包括 offline_access 在您的范围内（例如。， read:jira-work write:jira-work offline_access).这允许服务器自动刷新访问令牌。

Alternative: Using a Pre-existing OAuth Access Token (BYOT)

如果您运行的是外部管理atlassian OAuth 2.0访问令牌的大型系统的mcp-atlassian部分（例如，通过中央身份提供者或其他应用程序），您可以直接向此mcp服务器提供访问令牌。此方法绕过交互式设置向导和服务器的内部令牌管理（包括刷新功能）。

要求：

具有预期操作所需范围的有效Atlassian OAuth 2.0访问令牌。
相应的 ATLASSIAN_OAUTH_CLOUD_ID 对于您的Atlassian实例。

配置： 要使用此方法，请设置以下环境变量（或在启动服务器时使用相应的命令行标志）：

ATLASSIAN_OAUTH_CLOUD_ID：您的Atlassian云ID。（CLI： --oauth-cloud-id)
ATLASSIAN_OAUTH_ACCESS_TOKEN：您预先存在的OAuth 2.0访问令牌。（CLI: --oauth-access-token)

BYOT的重要注意事项：

令牌生命周期管理： 使用BYOT时，MCP服务器不处理令牌刷新。获取、刷新（到期前）和撤销访问令牌的责任完全在于您或提供令牌的外部系统。
未使用的变量： 标准OAuth客户端变量(ATLASSIAN_OAUTH_CLIENT_ID, ATLASSIAN_OAUTH_CLIENT_SECRET, ATLASSIAN_OAUTH_REDIRECT_URI, ATLASSIAN_OAUTH_SCOPE)都是不在配置BYOT时可以省略。
无安装向导： 这 --oauth-setup 向导不适用，也不应用于此方法。
无令牌缓存卷： 用于令牌存储的Docker卷挂载（例如。， -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian")如果您仅使用BYOT方法，则也没有必要，因为此服务器不存储或管理令牌。
范围： 提供的访问令牌必须已经具有您要执行的Jira操作所需的权限（范围）。

此选项在OAuth凭据管理集中或由其他基础架构组件处理的情况下非常有用。

[！提示] 多云OAuth支持：如果您正在构建一个用户提供自己的OAuth令牌的多租户应用程序，请参阅多云OAuth支持关于最小配置设置的部分。

📦 2.安装

MCP Atlassian Jira作为Docker镜像分发。这是运行服务器的推荐方式，特别是对于IDE集成。确保你已经安装了Docker。

# Pull Pre-built Image
docker pull ghcr.io/amruthabesto28/JIRA-MCP:latest

🛠️ IDE集成

MCP Atlassian Jira旨在通过IDE集成与AI助手一起使用。

[！提示] 适用于克劳德桌面：直接查找并编辑配置文件：

视窗: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

对于光标：打开设置→ MCP → + 添加新的全局MCP服务器

⚙️ 配置方法

配置Docker容器有两种主要方法：

直接传递变量 （如下例所示）
使用环境文件 随着 --env-file 旗帜（以可折叠部分显示）

[！注意] 常见的环境变量包括：

JIRA_PROJECTS_FILTER：按项目键筛选（例如“PROJ、DEV、SUPPORT”）

READ_ONLY_MODE：设置为“true”以禁用写入操作

MCP_VERBOSE：设置为“true”以进行更详细的日志记录

MCP_LOGGING_STDOUT：设置为“true”以记录到stdout而不是stderr

ENABLED_TOOLS：要启用的工具名称的逗号分隔列表（例如，“jira_search，jira_get_issue”）

请参阅 .env.示例所有可用选项的文件。

📝 配置示例

方法1（直接传递变量）：

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

Alternative: Using Environment File

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/path/to/your/mcp-atlassian.env",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Server/Data Center Configuration

对于服务器/数据中心部署，使用直接变量传递：

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "JIRA_PERSONAL_TOKEN",
        "-e", "JIRA_SSL_VERIFY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_jira_pat",
        "JIRA_SSL_VERIFY": "false"
      }
    }
  }
}

[！注意] 集 JIRA_SSL_VERIFY 仅当您拥有自签名证书时，才会显示为“false”。

OAuth 2.0 Configuration (Cloud Only)

这些示例显示了如何配置 mcp-atlassian 在您的IDE（如Cursor或Claude Desktop）中使用OAuth 2.0 for Atlassian Cloud时。

标准OAuth 2.0流示例（使用安装向导）：

此配置适用于您使用服务器的内置OAuth客户端并完成 OAuth设置向导.

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "<path_to_your_home>/.mcp-atlassian:/home/app/.mcp-atlassian",
        "-e", "JIRA_URL",
        "-e", "ATLASSIAN_OAUTH_CLIENT_ID",
        "-e", "ATLASSIAN_OAUTH_CLIENT_SECRET",
        "-e", "ATLASSIAN_OAUTH_REDIRECT_URI",
        "-e", "ATLASSIAN_OAUTH_SCOPE",
        "-e", "ATLASSIAN_OAUTH_CLOUD_ID",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "ATLASSIAN_OAUTH_CLIENT_ID": "YOUR_OAUTH_APP_CLIENT_ID",
        "ATLASSIAN_OAUTH_CLIENT_SECRET": "YOUR_OAUTH_APP_CLIENT_SECRET",
        "ATLASSIAN_OAUTH_REDIRECT_URI": "http://localhost:8080/callback",
        "ATLASSIAN_OAUTH_SCOPE": "read:jira-work write:jira-work offline_access",
        "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_CLOUD_ID_FROM_SETUP_WIZARD"
      }
    }
  }
}

[！注意]

对于标准流量：

ATLASSIAN_OAUTH_CLOUD_ID 从 --oauth-setup 向导输出或为您的实例所知。

其他 ATLASSIAN_OAUTH_* 客户端变量来自Atlassian开发人员控制台中的OAuth应用程序。

JIRA_URL 对于您的云实例，始终需要。

卷装载(-v .../.mcp-atlassian:/home/app/.mcp-atlassian)对于保存向导获得的OAuth令牌，启用自动刷新至关重要。

预先存在的访问令牌（BYOT-自带令牌）示例：

此配置适用于您提供自己的外部管理的OAuth 2.0访问令牌时。

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "ATLASSIAN_OAUTH_CLOUD_ID",
        "-e", "ATLASSIAN_OAUTH_ACCESS_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_KNOWN_CLOUD_ID",
        "ATLASSIAN_OAUTH_ACCESS_TOKEN": "YOUR_PRE_EXISTING_OAUTH_ACCESS_TOKEN"
      }
    }
  }
}

[！注意]

对于BYOT方法：

你主要需要 JIRA_URL, ATLASSIAN_OAUTH_CLOUD_ID，以及 ATLASSIAN_OAUTH_ACCESS_TOKEN.

标准OAuth客户端变量(ATLASSIAN_OAUTH_CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, SCOPE)都是不使用。

令牌生命周期（例如，在令牌到期前刷新令牌并重新启动mcp-atlassian）是您的责任，因为服务器不会刷新BYOT令牌。

Proxy Configuration

MCP Atlassian Jira支持通过标准HTTP/HTTPS/SOCKS代理路由API请求。使用环境变量进行配置：

支持标准 HTTP_PROXY, HTTPS_PROXY, NO_PROXY, SOCKS_PROXY.
服务特定的覆盖是可用的（例如。， JIRA_HTTPS_PROXY, JIRA_NO_PROXY).
特定于服务的变量会覆盖该服务的全局变量。

将相关代理变量添加到 args （使用 -e)以及 env MCP配置的各个部分：

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "... existing Jira vars",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_PROXY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "... existing Jira vars": "...",
        "HTTP_PROXY": "http://proxy.internal:8080",
        "HTTPS_PROXY": "http://proxy.internal:8080",
        "NO_PROXY": "localhost,.your-company.com"
      }
    }
  }
}

代理URL中的凭据在日志中被屏蔽。如果你设置 NO_PROXY，对匹配主机的请求将得到尊重。

Custom HTTP Headers Configuration

MCP Atlassian Jira支持向所有API请求添加自定义HTTP头。此功能在出于安全、身份验证或路由目的需要额外标头的公司环境中特别有用。

自定义标头是使用逗号分隔的键=值对环境变量配置的：

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "-e", "JIRA_CUSTOM_HEADERS",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_jira_api_token",
        "JIRA_CUSTOM_HEADERS": "X-Forwarded-User=service-account,X-Company-Service=mcp-atlassian,X-Jira-Client=mcp-integration"
      }
    }
  }
}

安全注意事项：

自定义标头值在调试日志中被屏蔽，以保护敏感信息
确保自定义标头不与标准HTTP或Atlassian API标头冲突
如果已经使用基本身份验证或OAuth，请避免在自定义标头中包含敏感的身份验证令牌
标头随每个API请求一起发送-验证它们是否干扰API功能

Multi-Cloud OAuth Support

MCP Atlassian Jira支持多云OAuth场景，其中每个用户都连接到自己的Atlassian云实例。这对于多租户应用程序、聊天机器人或用户提供自己的OAuth令牌的服务非常有用。

最低OAuth配置：

启用最低OAuth模式（不需要客户端凭据）：

docker run -e ATLASSIAN_OAUTH_ENABLE=true -p 9000:9000 \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport streamable-http --port 9000

用户通过HTTP标头提供身份验证：
- Authorization: Bearer <user_oauth_token>
- X-Atlassian-Cloud-Id: <user_cloud_id>

集成示例（Python）：

import asyncio
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

user_token = "user-specific-oauth-token"
user_cloud_id = "user-specific-cloud-id"

async def main():
    # Connect to streamable HTTP server with custom headers
    async with streamablehttp_client(
        "http://localhost:9000/mcp",
        headers={
            "Authorization": f"Bearer {user_token}",
            "X-Atlassian-Cloud-Id": user_cloud_id
        }
    ) as (read_stream, write_stream, _):
        # Create a session using the client streams
        async with ClientSession(read_stream, write_stream) as session:
            # Initialize the connection
            await session.initialize()

            # Example: Get a Jira issue
            result = await session.call_tool(
                "jira_get_issue",
                {"issue_key": "PROJ-123"}
            )
            print(result)

asyncio.run(main())

配置说明：

每个请求都可以通过以下方式使用不同的云实例 X-Atlassian-Cloud-Id 头球
每个请求都隔离用户令牌-没有跨租户数据泄漏
回归全球 ATLASSIAN_OAUTH_CLOUD_ID 如果未提供标题
与标准OAuth 2.0承载令牌身份验证兼容

👥 HTTP传输配置

而不是使用 stdio，您可以使用以下任一方式将服务器作为持久HTTP服务运行：

sse （服务器发送事件）传输 /sse 端点
streamable-http 运输在 /mcp 端点

这两种传输类型都支持单用户和多用户身份验证：

身份验证选项：

单用户：使用通过环境变量配置的服务器级身份验证
多用户：每个用户提供自己的身份验证：
- 云：OAuth 2.0承载令牌
- 服务器/数据中心：个人访问令牌（PAT）

Basic HTTP Transport Setup

使用您选择的传输方式启动服务器：

# For SSE transport
docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport sse --port 9000 -vv

# OR for streamable-http transport
docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport streamable-http --port 9000 -vv

配置IDE（单用户示例）：

苏格兰和南方能源公司运输示例：

{
  "mcpServers": {
    "mcp-atlassian-http": {
      "url": "http://localhost:9000/sse"
    }
  }
}

流式HTTP传输示例：

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

Multi-User Authentication Setup

以下是一个使用流式HTTP传输设置多用户身份验证的完整示例：

首先，运行OAuth设置向导以配置服务器的OAuth凭据：

docker run --rm -i \
  -p 8080:8080 \
  -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
  ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

使用流式HTTP传输启动服务器：

docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport streamable-http --port 9000 -vv

配置IDE的MCP设置：

为Atlassian部署选择适当的授权方法：

云（OAuth 2.0）： 如果您的组织位于Atlassian Cloud上，并且您为每个用户都有OAuth访问令牌，请使用此选项。
服务器/数据中心（PAT）： 如果您在Atlassian服务器或数据中心上，并且每个用户都有一个个人访问令牌（PAT），请使用此选项。

云（OAuth 2.0）示例：

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>"
      }
    }
  }
}

服务器/数据中心（PAT）示例：

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

中所需的环境变量 .env:

JIRA_URL=https://your-company.atlassian.net
ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_app_client_id
ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_app_client_secret
ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback
ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work offline_access
ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_setup_wizard

[！注意]

服务器应该配置自己的回退身份验证（例如，通过API令牌、PAT的环境变量，或使用--OAuth-setup的自己的OAuth设置）。如果请求不包括用户特定的身份验证，则使用此选项。

OAuth：每个用户都需要从Atlassian OAuth应用程序中获得自己的OAuth访问令牌。

专利审查高速路：每个用户提供自己的个人访问令牌。

多云：对于OAuth用户，可以选择包括 X-Atlassian-Cloud-Id header指定要使用的Atlassian云实例

当提供API调用时，服务器将使用用户的令牌，如果没有，则返回到服务器身份验证

用户令牌应具有适合其所需操作的范围

工具

Jira关键工具

jira_get_issue：获取特定问题的详细信息
jira_search：使用JQL搜索问题
jira_create_issue：创建新问题
jira_update_issue：更新现有问题
jira_transition_issue：将问题转变为新的状态
jira_add_comment：向问题添加评论

View All Jira Tools

操作	Jira工具
阅读	`jira_search`
	`jira_get_issue`
	`jira_get_all_projects`
	`jira_get_project_issues`
	`jira_get_worklog`
	`jira_get_transitions`
	`jira_search_fields`
	`jira_get_agile_boards`
	`jira_get_board_issues`
	`jira_get_sprints_from_board`
	`jira_get_sprint_issues`
	`jira_get_link_types`
	`jira_batch_get_changelogs`*
	`jira_get_user_profile`
	`jira_download_attachments`
	`jira_get_project_versions`
写	`jira_create_issue`
	`jira_update_issue`
	`jira_delete_issue`
	`jira_batch_create_issues`
	`jira_add_comment`
	`jira_transition_issue`
	`jira_add_worklog`
	`jira_link_to_epic`
	`jira_create_sprint`
	`jira_update_sprint`
	`jira_create_issue_link`
	`jira_remove_issue_link`
	`jira_create_version`
	`jira_batch_create_versions`

*该工具仅在Jira Cloud上可用

工具过滤和访问控制

服务器提供两种方法来控制工具访问：

工具筛选：使用 --enabled-tools 旗帜或 ENABLED_TOOLS 环境变量，用于指定应提供哪些工具：

# Via environment variable
ENABLED_TOOLS="jira_get_issue,jira_search"

# Or via command line flag
docker run ... --enabled-tools "jira_get_issue,jira_search" ...

读/写控制：工具分为读取或写入操作。当 READ_ONLY_MODE 启用后，无论是否启用，只有读取操作可用 ENABLED_TOOLS 设置。

故障排除与调试

常见问题

身份验证失败:
- 对于云：检查您的API令牌（而不是您的帐户密码）
- 对于服务器/数据中心：验证您的个人访问令牌是否有效且未过期
SSL证书问题：如果使用服务器/数据中心时遇到SSL错误，请设置 JIRA_SSL_VERIFY=false
权限错误：确保您的Atlassian帐户有足够的权限访问项目
自定义标头问题：参见 “调试自定义标头” 下面的部分将分析和解决自定义标头的问题

调试自定义标头

要验证自定义标头是否正确应用，请执行以下操作：

启用调试日志：设置 MCP_VERY_VERBOSE=true 查看详细的请求日志

# In your .env file or environment
MCP_VERY_VERBOSE=true
MCP_LOGGING_STDOUT=true

检查标头解析：为了安全起见，日志中会显示带有掩码值的自定义标头：
```
DEBUG Custom headers applied: {'X-Forwarded-User': '***', 'X-ALB-Token': '***'}
```
验证服务特定标头：检查日志以确认使用了正确的标头：
```
DEBUG Jira request headers: service-specific headers applied
```

测试标题格式：确保标题字符串格式正确：

# Correct format
JIRA_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2

# Incorrect formats (will be ignored)
JIRA_CUSTOM_HEADERS="X-Custom=value1,X-Other=value2"  # Extra quotes
JIRA_CUSTOM_HEADERS=X-Custom: value1,X-Other: value2  # Colon instead of equals
JIRA_CUSTOM_HEADERS=X-Custom = value1               # Spaces around equals

安全说明：包含敏感信息（令牌、密码）的标头值在日志中会自动屏蔽，以防止意外暴露。

调试工具

# Using MCP Inspector for testing
npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

# For local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ...

# View logs
# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# Windows
type %APPDATA%\Claude\logs\mcp*.log | more

安全

永远不要共享API令牌
确保.env文件的安全性和私密性
看安全.md 最佳实践

贡献

我们欢迎为MCP Atlassian Jira做出贡献！如果你想贡献：

查看我们的贡献.md 详细的开发设置说明指南。
进行更改并提交拉取请求。

我们使用预提交挂钩来保证代码质量，并遵循语义版本控制来发布。

许可证

麻省理工学院授权-见许可证文件。这不是Atlassian的官方产品。