mcp-jira-stdio

MCP Jira Server

用于集成 Jira API 的模型上下文协议（MCP）服务。可直接通过 MCP 客户端（例如 Claude Desktop）读取、写入和管理 Jira 工单与项目。

⚡ Claude Code 快速安装

将此 MCP 服务添加到 Claude Code 的最快方式：

claude mcp add jira npx mcp-jira-stdio@latest \
  --env JIRA_BASE_URL=https://yourcompany.atlassian.net \
  --env [email protected] \
  --env JIRA_API_TOKEN=your-api-token

将值替换为实际的 Jira 凭据：

• JIRA_BASE_URL：Jira 实例的 URL（例如，https://yourcompany.atlassian.net）
• JIRA_EMAIL：Jira 账户邮箱
• JIRA_API_TOKEN：Jira API 令牌（在此生成）

完成！服务将自动配置并可立即使用。

替代方式：手动配置

如果你希望手动配置或使用 Claude Desktop，请参阅下方的配置部分。

🚀 快速开始

1. 前置条件

• Node.js v20 或更高版本
• Jira 实例（Cloud 或 Server）
• Jira API 令牌

2. 安装

# Install from npm
npm install -g mcp-jira-stdio

# Or install locally in your project
npm install mcp-jira-stdio

开发环境安装

# Clone the repository
git clone https://github.com/freema/mcp-jira-stdio.git
cd mcp-jira-stdio

# Install dependencies
npm install
# or using Task runner
task install

# Build the project
npm run build
# or
task build

3. 设置 Jira API

1. 前往 Jira 实例设置
2. 创建 API 令牌：
   • Jira Cloud：前往账户设置 → 安全 → 创建和管理 API 令牌
   • Jira Server：使用用户名和密码（或创建应用密码）
3. 记下 Jira 基础 URL（例如，https://yourcompany.atlassian.net）

4. 配置

根据提供的示例创建 .env 文件：

# Copy the example environment file
cp .env.example .env

# Edit .env with your actual Jira credentials
# Or use Task runner:
task env

.env 文件内容示例：

JIRA_BASE_URL=https://your-instance.atlassian.net
[email protected]
JIRA_API_TOKEN=your-api-token

注意： 在 https://id.atlassian.com/manage-profile/security/api-tokens 生成 API 令牌

5. 测试连接

# Test Jira connection
task jira:test

# List visible projects
task jira:projects

6. 配置 MCP 客户端

用于 Claude Code

使用快速安装命令（推荐）：

claude mcp add jira npx mcp-jira-stdio@latest \
  --env JIRA_BASE_URL=https://yourcompany.atlassian.net \
  --env [email protected] \
  --env JIRA_API_TOKEN=your-api-token

用于 Claude Desktop

添加到 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "jira": {
      "command": "mcp-jira-stdio",
      "env": {
        "JIRA_BASE_URL": "https://your-instance.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

替代方式：使用 npx

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["mcp-jira-stdio"],
      "env": {
        "JIRA_BASE_URL": "https://your-instance.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

添加配置后重启 Claude Desktop。

📦 可用工具

项目

• jira_get_visible_projects：获取用户可见的所有项目。
• jira_get_project_info：获取项目的详细信息（组件、版本、角色、洞察）。

问题

• jira_get_issue：按键检索问题详情（支持可选字段/展开）。
• jira_search_issues：使用 JQL 搜索 Jira 问题，支持分页和指定字段。
• jira_create_issue：在项目中创建新问题（类型、优先级、经办人、标签、组件）。
• jira_update_issue：更新现有问题（摘要、描述、优先级、经办人、标签、组件、修复版本）。
• jira_create_subtask：在父问题下创建子任务（自动检测子任务类型）。

评论

• jira_add_comment：向问题添加评论（可选按组/角色设置可见性）。

元数据与用户

• jira_get_create_meta：获取项目的创建元数据，显示所有可用字段（包括自定义字段）及其允许值。创建问题前发现必填字段的必备工具。
• jira_get_issue_types：列出问题类型（可选按项目筛选）。
• jira_get_users：搜索用户（按查询词、用户名或 accountId）。
• jira_get_priorities：列出可用的优先级。
• jira_get_statuses：列出可用状态（全局或特定项目）。
• jira_get_custom_fields：列出 Jira 中的所有自定义字段及其类型和架构。

我的工作

• jira_get_my_issues：检索分配给当前用户的问题（按更新时间排序）。

🛠️ 开发

开发命令

# Development mode with hot reload
npm run dev
task dev

# Build for production
npm run build
task build

# Type checking
npm run typecheck
task typecheck

# Linting
npm run lint
task lint

# Format code
npm run format
task fmt

# Run all checks
npm run check
task check

MCP Inspector

使用 inspector 调试你的 MCP 服务：

# Run inspector (production build)
npm run inspector
task inspector

# Run inspector (development mode)
npm run inspector:dev
task inspector:dev

注意：

• 启动时不再等待 Jira 连接。如果缺少 Jira 环境变量，服务仍会启动并列出工具；在设置 JIRA_BASE_URL、JIRA_EMAIL 和 JIRA_API_TOKEN 之前，工具调用会失败并显示清晰的身份验证错误。
• 连接测试仅在开发/测试环境中运行（NODE_ENV=development 或 test）。失败会被记录，但不会终止服务，因此 inspector 仍可显示工具。

测试

# Run tests
npm test
task test

# Run tests with coverage
npm run test:coverage
task test:coverage

# Watch mode
npm run test:watch
task test:watch

📋 项目结构

src/
├── index.ts              # Entry point & MCP server setup
├── config/
│   └── constants.ts      # API configuration & constants
├── tools/
│   ├── index.ts          # Tool exports
│   └── get-visible-projects.ts  # Get visible projects tool
├── types/
│   ├── common.ts         # Common types & interfaces
│   ├── jira.ts           # Jira API types
│   └── tools.ts          # Tool input/output schemas
└── utils/
    ├── jira-auth.ts      # Jira authentication & client
    ├── validators.ts     # Input validation with Zod
    ├── formatters.ts     # Response formatting
    ├── error-handler.ts  # Error handling
    └── api-helpers.ts    # Jira API helpers

🔧 工具使用示例

获取可见项目

// List all projects
jira_get_visible_projects({});

// List projects with additional details
jira_get_visible_projects({
  expand: ['description', 'lead', 'issueTypes'],
});

// List recent projects only
jira_get_visible_projects({
  recent: 10,
});

❗ 故障排除

常见问题

“身份验证失败”

• 验证 API 令牌是否正确
• 检查邮箱是否与 Jira 账户匹配
• 确保 Jira 基础 URL 正确（末尾没有斜杠）

“连接失败”

• 验证是否可以访问 Jira 实例
• 检查网络连接
• 确保已启用 Jira REST API

“权限被拒绝”

• 验证账户是否拥有必要权限
• 检查 Jira 中的项目权限
• 确保使用的是正确的 Jira 实例

MCP 连接问题

• 确保使用已构建的版本（dist/index.js）
• 检查 Claude Desktop 配置中的 Node.js 路径是否正确
• 查看 Claude Desktop 日志中的错误
• 使用 task inspector 进行调试

使用 npx 运行多个实例时超时

如果你同时运行多个 Claude Code 会话并遇到超时，这是由 npx 缓存/注册表锁定导致的，而非 MCP 服务本身。每个实例都会尝试验证软件包，从而造成冲突。要解决此问题，请改为全局安装软件包：

npm install -g mcp-jira-stdio
claude mcp add jira mcp-jira-stdio \
  --env JIRA_BASE_URL=... \
  --env JIRA_EMAIL=... \
  --env JIRA_API_TOKEN=...

调试命令

# Test Jira connection
task jira:test

# List projects (test API connectivity)
task jira:projects

# Run MCP inspector for debugging
task inspector:dev

# Check all configuration
task check

如果 inspector 显示 SSE 错误且服务立即退出，请确保没有因无效凭据而强制提前退出。根据当前行为，服务不应因缺少凭据而退出；导出 Jira 变量以测试这些工具：

export JIRA_BASE_URL="https://your-instance.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-api-token"
npm run inspector

🔍 环境变量

变量	必需	描述	示例
JIRA_BASE_URL	是	Jira 实例 URL	https://company.atlassian.net
JIRA_EMAIL	是	你的 Jira 邮箱	[email protected]
JIRA_API_TOKEN	是	Jira API 令牌	ATxxx...
NODE_ENV	否	环境模式	development 或 production

🤝 参与贡献

1. Fork 此代码仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 运行测试和代码检查（task check）
4. 提交更改（git commit -m 'Add some amazing feature'）
5. 将分支推送到远程仓库（git push origin feature/amazing-feature）
6. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

MCP 配置设置

交互式配置 Claude Desktop 以使用此 MCP 服务：

npm run setup:mcp

此脚本将：

• 在需要时构建项目并检测 Node 路径
• 提示输入 JIRA_BASE_URL、JIRA_EMAIL、JIRA_API_TOKEN
• 将 jira 条目保存到 Claude Desktop 配置中，或打印 JSON
• 可选择为开发生成本地 .env