AI导哈

Atlassian集成服务器

一个用于Atlassian Jira和Confluence集成的模型上下文协议（MCP）服务器，支持API令牌认证，提供Jira问题管理和Confluence页面操作功能。

  • by dongood
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 dongood/atlassian-mcp-server

使用说明

Atlassian MCP服务器

模型上下文协议（MCP）服务器，用于使用API令牌身份验证的Atlassian Jira和Confluence集成。

特性

  • 长期身份验证：使用API令牌而不是OAuth进行持久访问
  • Jira集成：创建、更新、搜索和管理Jira问题（包括文件附件）
  • 汇流集成：读取、创建和更新Confluence页面
  • 自定义字段映射：使用友好的名称（例如“sprint”）而不是神秘的字段ID（例如“customfield_10560”）
  • TypeScript：完全打字，以获得更好的开发体验
  • MCP兼容：与Claude Code CLI和Claude Desktop配合使用

先决条件

  • Node.js 20.x或更高版本
  • Atlassian Cloud帐户（例如yoursite.Atlassian.net）
  • Atlassian API令牌

安装

  1. 克隆或下载此存储库：
cd /Users/dongood/SourceCode/Repos/_dongood/atlassian-mcp-server
  1. 安装依赖项：
npm install
  1. 构建TypeScript代码：
npm run build

创建Atlassian API令牌

  1. 访问https://id.atlassian.com/manage-profile/security/api-tokens
  2. 点击 创建API令牌
  3. 给它一个描述性的名称（例如“MCP服务器”）
  4. 复制令牌（您将无法再次看到它）
  5. 安全存放

配置

环境变量

服务器需要以下环境变量：

  • ATLASSIAN_SITE_URL：您的Atlassian网站URL（例如。， https://avetta.atlassian.net)
  • ATLASSIAN_USER_EMAIL：您与Atlassian帐户关联的电子邮件地址
  • ATLASSIAN_API_TOKEN：您在上面创建的API令牌
  • ATLASSIAN_FIELD_MAPPINGS_PATH （可选）：自定义字段映射JSON文件的路径

适用于Claude Code CLI

全局配置 （推荐）：编辑 ~/.claude.json 并在下面添加服务器 mcpServers 钥匙。这使得服务器在所有项目中都可用，而不会出现每个项目的审批提示：

{
  "mcpServers": {
    "atlassian": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/atlassian-mcp-server/build/index.js"],
      "env": {
        "ATLASSIAN_SITE_URL": "https://yoursite.atlassian.net",
        "ATLASSIAN_USER_EMAIL": "your.email@example.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

项目特定配置：创建 .mcp.json 在您的项目根目录中。请注意，中定义的服务器 .mcp.json Claude Code开始时，每个项目都需要批准文件：

{
  "mcpServers": {
    "atlassian": {
      "command": "node",
      "args": ["/path/to/atlassian-mcp-server/build/index.js"],
      "env": {
        "ATLASSIAN_SITE_URL": "https://yoursite.atlassian.net",
        "ATLASSIAN_USER_EMAIL": "your.email@example.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

重要：用实际值替换占位符。

适用于克劳德桌面

编辑Claude Desktop配置文件：

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

添加此配置：

{
  "mcpServers": {
    "atlassian": {
      "command": "node",
      "args": ["/Users/dongood/SourceCode/Repos/_dongood/atlassian-mcp-server/build/index.js"],
      "env": {
        "ATLASSIAN_SITE_URL": "https://avetta.atlassian.net",
        "ATLASSIAN_USER_EMAIL": "your.email@example.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

自定义字段映射

Jira自定义字段具有神秘的ID，如 customfield_10560。此服务器允许您将它们映射到友好名称。

配置字段映射

  1. 编辑 config/field-mappings.json:
{
  "sprint": "customfield_10560",
  "story_points": "customfield_10016",
  "epic_link": "customfield_10014",
  "team": "customfield_10100"
}
  1. 服务器将自动从以下位置加载此文件 config/ 目录
  2. 您现在可以使用 "sprint" 而不是 "customfield_10560" 在MCP工具调用中

查找自定义字段ID

要查找自定义字段的实际字段ID，请执行以下操作：

  1. 通过Jira用户界面:

    • 转到Jira设置→ 问题→ 自定义字段
    • 找到您的字段并记下其ID

  2. 通过API:

    • 获取已填充该字段的任何问题
    • 查看原始JSON响应-自定义字段显示为 customfield_XXXXX

  3. 使用MCP服务器的示例:

    Use atlassian_get_jira_issue with issueKey "PROJ-123"
Look in the fields object for customfield_* entries

使用字段映射

创建或编辑问题时，您可以使用以下任一方法：

  • 友好名称： { "sprint": "Sprint 42" }
  • 实际字段ID： { "customfield_10560": "Sprint 42" }

这两种格式都有效——服务器处理翻译。

可用工具

实用工具

  • atlassian_health_check -测试连接和身份验证
  • atlassian_get_user_info -获取当前用户信息

Jira工具

  • atlassian_get_jira_issue -按密钥或ID获取问题
  • atlassian_create_jira_issue -创建新问题
  • atlassian_edit_jira_issue -更新问题字段
  • atlassian_search_jira_issues -使用JQL搜索
  • atlassian_add_jira_comment -向问题添加评论
  • atlassian_transition_jira_issue -更改问题状态
  • atlassian_get_jira_transitions -获取可用转换
  • atlassian_get_jira_projects -列出项目
  • atlassian_get_project_issue_types -获取项目的问题类型
  • atlassian_add_jira_attachment -上传问题的文件附件
  • atlassian_get_jira_attachments -列出问题的附件
  • atlassian_delete_jira_attachment -按ID删除附件
  • atlassian_lookup_jira_user -按姓名/电子邮件查找用户

汇流工具

  • atlassian_get_confluence_page -按ID获取页面
  • atlassian_search_confluence_cql -使用CQL搜索
  • atlassian_get_confluence_spaces -列出空间
  • atlassian_get_space_pages -在空间中获取页面
  • atlassian_create_confluence_page -创建新页面
  • atlassian_update_confluence_page -更新现有页面
  • atlassian_get_page_children -获取子页面

文件附件

附件工具允许将文件从本地文件系统上传到Jira issues。这是有效的，因为MCP服务器与AI代理（Claude Code）在同一台机器上作为本地进程运行，使其能够直接访问文件系统。

Claude Code  --MCP (JSON: file path as string)-->  MCP Server  --HTTP (multipart/form-data)-->  Jira API

MCP协议本身只传递JSON（字符串、数字、对象）。它没有本机二进制或多部分支持。诀窍是AI代理通过一个 文件路径作为字符串参数，而MCP服务器处理其余部分：从磁盘读取文件，构建多部分/form-data请求，并将其上传到Jira的rest API v3附件端点。

此方法要求MCP服务器在本地运行 （与附加的文件相同的文件系统）。如果MCP服务器在远程运行，文件路径在远程主机上将毫无意义，您需要一种替代方法，如base64编码内容或共享存储URL。

Jira附件API要求

Jira REST API v3附件端点(POST /rest/api/3/issue/{key}/attachments)要求：

  • X-Atlassian-Token: no-check 标头（CSRF保护旁路，Jira为此端点要求）
  • Content-Type: multipart/form-data 文件在 file 表单字段
  • 标准基本Auth（与所有其他Jira API调用相同）

使用示例

"Attach /Users/me/docs/report.pdf to BI-10341"
"List all attachments on PROJ-123"
"Delete attachment 12345 from the issue"

测试

您可以使用MCP检查器测试服务器：

npx @modelcontextprotocol/inspector node build/index.js

运行前设置环境变量：

export ATLASSIAN_SITE_URL="https://avetta.atlassian.net"
export ATLASSIAN_USER_EMAIL="your.email@example.com"
export ATLASSIAN_API_TOKEN="your-api-token"
npx @modelcontextprotocol/inspector node build/index.js

示例用法

在Claude Code或Claude Desktop中配置后，您可以自然地与Jira和Confluence交互：

Jira示例:

  • “获取问题BI-9956的详细信息”
  • “在PROJ项目中创建一个新错误，摘要为‘登录页面已损坏’”
  • “搜索分配给我的所有打开的Bug”
  • “在PROJ-123中添加一条评论，说‘已在最新版本中修复’”
  • “将PROJ-456移至进行中”

汇流示例:

  • “获取Confluence页面123456789的内容”
  • “在Confluence上搜索关于‘架构’的页面”
  • “列出ENG空间中的所有页面”
  • “在12345空白处创建一个名为“Sprint回顾”的新页面”

发展

构建

npm run build

跑

npm start

开发模式（构建+运行）

npm run dev

API 文档

  • Jira REST API v3: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
  • Confluence REST API v2: https://developer.atlassian.com/cloud/confluence/rest/v2/

故障排除

身份验证错误

如果你收到401错误：

  1. 验证您的电子邮件和API令牌是否正确
  2. 确保API令牌尚未过期
  3. 检查您的用户是否可以访问Jira/Confluence网站

权限错误

如果你收到403个错误：

  1. 验证您是否有权访问项目/空间
  2. 检查您的用户是否具有所需的权限（例如，创建问题、编辑页面）

未找到字段错误

如果自定义字段不起作用：

  1. 验证您的字段ID field-mappings.json 是正确的
  2. 确保该字段存在于项目/问题类型中
  3. 检查字段是否未被隐藏或限制

许可证

麻省理工学院

相关 MCP