AI导哈

Atlassian集成服务器

一个用于与Atlassian产品（Confluence和Jira）集成的MCP服务器，提供文档管理、搜索和导出功能。

  • by Vijay-Duke
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Vijay-Duke/mcp-atlassian

使用说明

MCP Atlassian服务器

这是一个经过维护的叉子 维贾伊·杜克/mcp阿特拉西安

为什么会有这个分叉： 2026年1月，Atlassian删除了 /rest/api/3/search 完全破坏了原始包中的所有Jira搜索功能。这个叉子迁移到新的 /rest/api/3/search/jql 端点，并实现了新的基于光标的分页。A. PR已提交 但截至目前，该回购中有14多个未合并的PR。

安装此叉子： npm install @efithor/mcp-atlassian --registry=https://npm.pkg.github.com

用于与Atlassian产品（Confluence和Jira）集成的模型上下文协议（MCP）服务器。该服务器为AI助手提供了与Atlassian Cloud API交互的工具，实现了文档管理、搜索和导出功能。

特性

汇流集成

  • 阅读和搜索：访问页面、空间和内容
  • 内容管理：创建、更新页面和评论
  • 页面层次结构：导航父/子页面关系
  • 出口：将页面导出为HTML或Markdown格式，并嵌入图像
  • 附件：列出、下载和上传附件
  • 标签：管理页面标签
  • 用户：查找和查询用户，跟踪个人活动
  • 仪表版：查看最近的页面和提及

Jira集成

  • 问题：阅读和搜索问题，获取个人任务
  • 项目：列出并探索项目
  • 木板和Sprints：列出公告板、查看冲刺、跟踪当前工作
  • 评论：为问题添加评论
  • 问题创建：使用自定义字段创建新问题
  • 用户管理：获取当前用户详细信息
  • 仪表版：查看您的未决问题和冲刺任务

安装

选项1:GitHub包（推荐）

首先，将npm配置为使用GitHub Packages @efithor 范围。添加到您的 ~/.npmrc:

@efithor:registry=https://npm.pkg.github.com

然后安装：

# Install globally
npm install -g @efithor/mcp-atlassian

# Or install locally
npm install @efithor/mcp-atlassian

选项2：克隆和构建

# Clone this fork
git clone https://github.com/Efithor/mcp-atlassian.git
cd mcp-atlassian

# Install dependencies
npm install

# Build TypeScript
npm run build

选项3：直接从GitHub安装

# Install directly from this fork
npm install -g github:Efithor/mcp-atlassian

# Or install in your project
npm install github:Efithor/mcp-atlassian

配置

环境变量

创建一个 .env 根目录中的文件：

ATLASSIAN_BASE_URL=https://yourdomain.atlassian.net
ATLASSIAN_EMAIL=your-email@example.com
ATLASSIAN_API_TOKEN=your-api-token

获取API令牌

  1. 登录 Atlassian帐户设置
  2. 点击“创建API令牌”
  3. 给它一个标签并复制令牌
  4. 在您的 .env 文件

MCP设置配置

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

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

选项1：安装npm后

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "npx",
      "args": ["@efithor/mcp-atlassian"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://yourdomain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

选项2：从本地克隆

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "node",
      "args": ["/path/to/your/mcp-atlassian/dist/index.js"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://yourdomain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

典型路径示例：

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "node",
      "args": ["~/projects/mcp-atlassian/dist/index.js"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://yourdomain.atlassian.net",
        "ATLASSIAN_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

选项3：使用uvx直接从GitHub（即将推出）

您可以直接从GitHub运行服务器，而无需克隆：

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Efithor/mcp-atlassian.git", "mcp-atlassian"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://yourdomain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

注： uvx方法要求为Python打包正确配置包。这是计划在未来发布的。

可用工具

汇流工具

工具 说明
get_confluence_current_user 获取已验证用户的详细信息
get_confluence_user 获取特定用户的详细信息
search_confluence_pages_by_user 按用户活动搜索页面
list_user_confluence_pages 列出用户编写的页面
list_user_confluence_attachments 列出用户上传的附件
read_confluence_page 按ID或标题阅读Confluence页面
search_confluence_pages 使用CQL（汇流查询语言）搜索页面
list_confluence_spaces 列出所有可访问的空间
get_confluence_space 获取特定空间的详细信息
create_confluence_page 创建新页面
update_confluence_page 更新现有页面内容
list_confluence_page_children 列出页面的子页面
list_confluence_page_ancestors 获取页面的父层次结构
export_confluence_page 将页面导出为HTML或Markdown格式，并嵌入图像
list_confluence_attachments 列出页面附件
download_confluence_attachment 下载特定附件
upload_confluence_attachment 将文件上传到页面
download_confluence_page_complete 下载包含所有内容的页面
add_confluence_comment 向页面添加评论
list_confluence_page_labels 获取页面标签
add_confluence_page_label 向页面添加标签
find_confluence_users 搜索用户
get_my_recent_confluence_pages 列出您最近的页面
get_confluence_pages_mentioning_me 查找提及您的页面

Jira工具

工具 说明
get_jira_current_user 获取已验证用户的详细信息
get_jira_user 获取特定用户的详细信息
search_jira_issues_by_user 按用户参与度搜索问题
list_user_jira_issues 按用户角色列出问题，并进行日期筛选
get_user_jira_activity 跟踪用户活动，包括评论和转换
get_user_jira_worklog 获取带有格式化总计的时间跟踪条目
read_jira_issue 按密钥读取问题详细信息
search_jira_issues 使用JQL搜索问题
list_jira_projects 列出所有可访问的项目
create_jira_issue 创建新问题
add_jira_comment 向问题添加评论
list_jira_boards 列出可访问的Scrum/看板板
list_jira_sprints 列出板上的冲刺
get_jira_sprint 获取详细的冲刺信息
get_my_tasks_in_current_sprint 让你的任务处于主动冲刺状态
get_my_open_issues 获取所有未解决的问题

使用示例

导出汇流页

// Export as HTML (raw content with embedded images)
{
  "tool": "export_confluence_page",
  "arguments": {
    "pageId": "123456789",
    "format": "html"
  }
}

// Export as Markdown with metadata
{
  "tool": "export_confluence_page",
  "arguments": {
    "pageId": "123456789",
    "format": "markdown"
  }
}

搜索汇流

{
  "tool": "search_confluence_pages",
  "arguments": {
    "cql": "space=DEV AND text~'architecture'",
    "limit": 10
  }
}

创建Jira问题

{
  "tool": "create_jira_issue",
  "arguments": {
    "projectKey": "PROJ",
    "issueType": "Task",
    "summary": "Implement new feature",
    "description": "Detailed description here",
    "priority": "Medium"
  }
}

获取Sprint任务

// Get your tasks in the current sprint
{
  "tool": "get_my_tasks_in_current_sprint",
  "arguments": {
    "projectKey": "PROJ"
  }
}

// Get all your open issues
{
  "tool": "get_my_open_issues",
  "arguments": {
    "projectKeys": ["PROJ1", "PROJ2"],
    "maxResults": 50
  }
}

与板和Sprints一起工作

// List boards for a project
{
  "tool": "list_jira_boards",
  "arguments": {
    "projectKeyOrId": "PROJ",
    "type": "scrum"
  }
}

// Get active sprints for a board
{
  "tool": "list_jira_sprints",
  "arguments": {
    "boardId": 123,
    "state": "active"
  }
}

用户特定的Jira操作

// Get user details
{
  "tool": "get_jira_user",
  "arguments": {
    "username": "john.doe"
  }
}

// Search issues by user involvement
{
  "tool": "search_jira_issues_by_user",
  "arguments": {
    "username": "john.doe",
    "searchType": "assignee",
    "status": "In Progress",
    "maxResults": 20
  }
}

// Get user's work logs
{
  "tool": "get_user_jira_worklog",
  "arguments": {
    "username": "john.doe",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "projectKeys": ["PROJ1", "PROJ2"]
  }
}

// Track user activity
{
  "tool": "get_user_jira_activity",
  "arguments": {
    "username": "john.doe",
    "activityType": "all",
    "days": 7
  }
}

内容格式支持

标记语言↔ 汇流存储格式

服务器会自动在Markdown和Confluence的存储格式之间进行转换：

  • 在创建/更新页面时用Markdown写内容
  • 读取存储格式或转换为Markdown的页面
  • 保留格式、链接和结构

导出格式

  • 超文本标记语言：原始Confluence HTML，所有图像都嵌入为base64数据URI
  • 标记语言：使用YAML frontmatter清理Markdown，包括元数据和嵌入图像

发展

# Run in development mode with console logging
npm run dev

# Build for production
npm run build

# Run built server in MCP mode (no console output)
npm start

# Run built server in development mode (with console output)
npm run start:dev

# Run tests
npm test

日志记录行为

服务器默认为MCP模式，禁用控制台输出以防止干扰JSON-RPC协议。控制台日志记录仅在以下情况下启用 MCP_SERVER_MODE=false 已设置，由自动完成 dev 和 start:dev 脚本。

项目结构

mcp-atlassian/
├── src/
│   ├── index.ts                 # Main server entry point
│   ├── types/                   # TypeScript type definitions
│   ├── confluence/
│   │   ├── handlers.ts          # Confluence API handlers
│   │   └── tools.ts             # Tool definitions
│   ├── jira/
│   │   ├── handlers.ts          # Jira API handlers
│   │   └── tools.ts             # Tool definitions
│   └── utils/
│       ├── http-client.ts       # Axios HTTP client setup
│       ├── content-converter.ts # Markdown ↔ Storage conversion
│       └── export-converter.ts  # HTML/Markdown export utilities
├── dist/                        # Compiled JavaScript
├── .env                         # Environment variables (not in git)
├── package.json
└── tsconfig.json

安全说明

  • API令牌存储在环境变量中，而不是存储在代码中
  • 使用API令牌（而不是密码）进行基本身份验证
  • 所有请求都是通过HTTPS发出的
  • 仅支持Atlassian Cloud（不支持服务器/数据中心）

局限性

  • 未执行删除操作（出于安全考虑）
  • 导出为PDF需要浏览器转换（HTML→ 打印→ PDF)
  • 某些Confluence宏可能无法完全转换为Markdown
  • 基于Atlassian Cloud API限制适用的费率限制

CI/CD管道

该项目使用GitHub Actions进行持续集成和部署。

工作流

🔄 持续集成(ci.yml)

  • 触发器：推送到主/开发，拉取请求
  • 工作:
    • 测试：在Node.js 18.x、20.x和22.x上运行测试
    • 构建：编译TypeScript并验证构建
    • 棉绒：类型检查和安全审计
    • 验证包：确保包装尺寸和结构

📦 发布到npm(publish.yml)

  • 触发器：GitHub发布，手动调度
  • 特性:
    • 自动版本碰撞
    • 带出处的npm发布
    • GitHub发布创建
    • 变更日志更新

🔒 安全扫描(security.yml)

  • 触发器：推送到主、PR、每周时间表
  • 扫描:
    • npm漏洞审计
    • CodeQL分析
    • OWASP依赖性检查
    • Snyk安全扫描（可选）

🏷️ 发布管理(release.yml)

  • 触发器：版本标签，手动调度
  • 特性:
    • 自动生成变更日志
    • GitHub发布创建
    • 构建工件附件
    • 发行说明格式

✅ PR验证(pr-validation.yml)

  • 触发器：拉取请求事件
  • 检查:
    • 语义PR标题验证
    • PR尺寸标签
    • 根据更改的文件自动标记

🤖 自动依赖关系更新

Dependabot配置为：

  • 每周检查npm依赖更新
  • 每周查看GitHub操作更新
  • 将非主要更新分组在一起
  • 创建带有适当标签的PR

设置CI/CD

必需的GitHub机密

  1. NPM令牌：用于发布的npm身份验证令牌

    • 生成时间：https://www.npmjs.com/settings/YOUR_USERNAME/tokens
    • 所需范围： publish

  2. SNYK_TOKEN （可选）：用于Snyk安全扫描

    • 来自：https://app.snyk.io/account

分支保护

推荐的分支保护规则 main:

  • 合并前需要公关审查
  • 要求状态检查通过（CI测试）
  • 要求分支机构保持最新状态
  • 将管理员纳入限制范围

本地开发

在推动更改之前：

# Run tests locally
npm test

# Build the project
npm run build

# Check for security vulnerabilities
npm audit

# Type check
npx tsc --noEmit

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

致谢

内置：

贡献者

感谢这些了不起的人(表情符号键):


Vijay Iyengar
💻 📖 🚧 👀 ⚠️ 🚇

该项目遵循 所有贡献者 规范。欢迎任何形式的贡献！

相关 MCP