Jira MCP Server

Jira MCP Server

Claude から Jira を直接操作するための、拡張された Model Context Protocol サーバーです。

このサーバーを使用すると、Model Context Protocol に対応した Claude などの AI アシスタントが Jira インスタンスを直接操作し、次のような幅広いプロジェクト管理タスクを実行できます。

• プロジェクト情報と課題の取得
• 課題とサブタスクの作成および更新
• 課題のワークフローとトランジションの管理
• 課題リンクと依存関係の作成
• コメントの追加と課題フィールドの管理
• ユーザー管理と担当者の割り当て
• 効率的な課題管理のための一括操作

Features

• Jira API の完全統合：Jira の機能に幅広くアクセスできます
• 書式設定の強化：コードブロックとインライン書式に対応した、Markdown から Atlassian Document Format（ADF）への変換機能の改善
• 入力検証：Zod を使用した堅牢なスキーマ検証
• エラー処理の改善：詳細なエラーメッセージと適切なエラー復旧
• カスタムフィールド対応：カスタム Jira フィールドを簡単に設定できます
• ステータス遷移：高度なワークフロー管理
• 一括操作：課題の一括操作（更新、削除）に対応
• きめ細かなラベル／コンポーネント管理：ラベルとコンポーネントの追加、削除、置換
• 設定可能なログ出力：環境変数でログの詳細度を制御できます

Prerequisites

• Node.js 18 以降
• Jira Cloud または Server インスタンス
• Jira API トークン（Cloud の場合）またはユーザー名／パスワード（Server の場合）
• Claude Desktop またはその他の MCP 対応 AI アシスタント

Installation

1. このリポジトリをクローンします。

   git clone https://github.com/yourusername/jira-server.git
   cd jira-server
   

2. 依存関係をインストールします。

   npm install
   

3. 環境変数を設定します。

   cp .env.example .env
   

4. .env ファイルを編集し、Jira の認証情報を設定します。

   JIRA_HOST=your-instance.atlassian.net
   [email protected]
   JIRA_API_TOKEN=your-api-token
   

5. サーバーをビルドします。

   npm run build
   

Usage

サーバーの起動

npm start

開発モード

自動リロードを有効にして開発する場合：

npm run dev

Lint とフォーマット

# Run ESLint
npm run lint

# Format code with Prettier
npm run format

Claude Desktop の設定

この MCP サーバーを Claude Desktop で使用するには：

1. 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

2. Jira MCP サーバーを設定に追加します。

   {
     "mcp_servers": [
       {
         "name": "jira-server",
         "command": "npm start",
         "cwd": "/absolute/path/to/jira-server",
         "env": {
           "JIRA_HOST": "your-instance.atlassian.net",
           "JIRA_EMAIL": "[email protected]",
           "JIRA_API_TOKEN": "your-api-token",
           "JIRA_API_VERSION": "3",
           "JIRA_CUSTOM_FIELDS": "summary,description,status,priority,assignee,issuetype,parent,subtasks",
           "LOG_LEVEL": "info"
         }
       }
     ]
   }
   

   /absolute/path/to/jira-server を、クローンしたリポジトリの絶対パスに置き換えてください。

3. Claude Desktop を再起動して、変更を適用します。

利用可能なツール

プロジェクト情報

// Get project information
{
  projectKey: "PROJECT",
  expand: ["lead", "description", "url"] // Optional
}

// List all available issue types
// No parameters required

// List all available Jira fields
// No parameters required

// List all available issue link types
// No parameters required

ユーザー管理

// Get user's account ID by email
{
  email: "[email protected]"
}

// Add a watcher to an issue
{
  issueKey: "PROJECT-123",
  username: "[email protected]"
}

課題の取得

// Get all issues in a project
{
  projectKey: "PROJECT"
}

// Get issues with JQL filtering
{
  projectKey: "PROJECT",
  jql: "status = 'In Progress' AND assignee = currentUser()"
}

// Get more issues at once (default: 50)
{
  projectKey: "PROJECT",
  maxResults: 100
}

// Get specific fields
{
  projectKey: "PROJECT",
  fields: ["summary", "status", "assignee", "labels"]
}

課題の作成

// Create a standard issue
{
  projectKey: "PROJECT",
  summary: "Issue title",
  issueType: "Task",  // or "Story", "Bug", etc.
  description: "Detailed description",
  assignee: "[email protected]",
  labels: ["frontend", "urgent"],
  components: ["ui", "api"],
  priority: "High"
}

// Create a subtask
{
  projectKey: "PROJECT",
  summary: "Subtask title",
  issueType: "Subtask",
  description: "Subtask details",
  assignee: "[email protected]",
  parent: "PROJECT-123"
}

課題の更新

// Update issue fields
{
  issueKey: "PROJECT-123",
  summary: "Updated title",
  description: "New description",
  assignee: "[email protected]",
  status: "In Progress",
  priority: "High", 
  labels: ["frontend", "updated"],
  components: ["ui"]
}

課題の一括更新

// Update multiple issues with the same values
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  priority: "High",
  status: "In Progress"
}

// Add labels to multiple issues (preserves existing labels)
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  addLabels: ["urgent", "sprint-5"]
}

// Remove labels from multiple issues
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  removeLabels: ["outdated"]
}

// Replace all labels on multiple issues
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  setLabels: ["frontend", "sprint-6"]
}

// Add components to multiple issues
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  addComponents: ["api"]
}

// Complex bulk update
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  status: "In Progress",
  priority: "High",
  assignee: "[email protected]",
  addLabels: ["sprint-6"],
  removeLabels: ["backlog"],
  addComponents: ["api"]
}

課題のリンク

// Create issue link
{
  linkType: "Blocks",  // from list_link_types
  inwardIssueKey: "PROJECT-124",  // blocked issue
  outwardIssueKey: "PROJECT-123",  // blocking issue
  comment: "Blocking due to dependency" // Optional
}

課題の削除

// Delete single issue
{
  issueKey: "PROJECT-123"
}

// Delete issue with subtasks
{
  issueKey: "PROJECT-123",
  deleteSubtasks: true
}

// Delete multiple issues
{
  issueKeys: ["PROJECT-123", "PROJECT-124"]
}

ワークフロー管理

// Get available transitions
{
  issueKey: "PROJECT-123"
}

// Transition an issue by transition name
{
  issueKey: "PROJECT-123",
  transitionName: "In Progress"
}

// Transition an issue by transition ID with comment
{
  issueKey: "PROJECT-123",
  transitionId: "31",
  comment: "Moving to in progress as development has started"
}

// Transition with additional fields
{
  issueKey: "PROJECT-123",
  transitionName: "Done",
  fields: {
    "resolution": { 
      "name": "Fixed" 
    }
  }
}

課題のコメント

// Add a comment
{
  issueKey: "PROJECT-123",
  body: "This is a comment with **bold** and *italic* formatting"
}

// Add a comment with visibility restrictions
{
  issueKey: "PROJECT-123",
  body: "This comment is only visible to a specific role",
  visibility: {
    type: "role",
    value: "Administrators"
  }
}

テキストの書式設定

このサーバーは、説明とコメントで拡張された Markdown 形式の書式設定に対応しています。

• 段落：空行で区切ります
• リスト：箇条書きには - または * 、番号付きリストには 1. を使用します
• 見出し：# 構文（# Header 1、## Header 2）を使用するか、行末に : を付けて空行を続けます
• テキストの書式設定：**bold**、*italic*、`code` を使用します
• コードブロック：コードブロックにはトリプルバッククォート（```）を使用します。言語の指定は任意です

例：

# Issue Description

This issue needs to be addressed **urgently**.

## Requirements:
- Implement the API endpoint
- Add proper error handling
- Write unit tests

Steps to reproduce:
1. Navigate to the dashboard
2. Click on the settings icon
3. Observe the error message

```javascript
// Current problematic code:
function getData() {
  return fetch('/api/data').then(res => res.json());
}
```

*Note*: This is blocking the release.

エラー処理

このサーバーは、次のエラーについて詳細なエラーメッセージを提供します。

• 無効なパラメーター
• 認証の問題
• 必須フィールドの不足
• 権限の問題
• リソースが見つからないエラー
• API のレート制限
• ワークフローの検証エラー

ログ出力

LOG_LEVEL 環境変数を設定すると、ログの詳細度を制御できます。

LOG_LEVEL=debug   # Most verbose, shows all details
LOG_LEVEL=info    # Default, shows general information
LOG_LEVEL=warn    # Shows only warnings and errors
LOG_LEVEL=error   # Shows only errors

カスタマイズ

カスタムフィールド

カスタム Jira フィールドを使用するには、JIRA_CUSTOM_FIELDS 環境変数に追加します。

JIRA_CUSTOM_FIELDS=summary,description,status,priority,assignee,issuetype,parent,subtasks,customfield_10001,customfield_10002

その後、リクエストでこれらのカスタムフィールドを使用できます。

// Update with custom fields
{
  issueKey: "PROJECT-123",
  customFields: {
    "customfield_10001": "Custom value",
    "customfield_10002": { "value": "Option 1" }
  }
}

フィールドの種類

カスタムフィールドによって、必要な形式が異なる場合があります。

• テキストフィールド：単純な文字列値
• 選択／オプションフィールド：value プロパティを持つオブジェクト
• ユーザーフィールド：id プロパティ（アカウント ID）を持つオブジェクト
• 複数選択フィールド：value プロパティを持つオブジェクトの配列
• 日付フィールド：ISO 形式の文字列

例：

{
  issueKey: "PROJECT-123",
  customFields: {
    "customfield_10001": "Text value",               // Text field
    "customfield_10002": { "value": "Option 1" },    // Select field
    "customfield_10003": { "id": "123456:abcdef" },  // User field
    "customfield_10004": [                           // Multi-select field
      { "value": "Option 1" },
      { "value": "Option 2" }
    ],
    "customfield_10005": "2023-04-30"                // Date field
  }
}

開発

プロジェクト構成

jira-server/
├── src/
│   ├── index.ts             # Main server entry point
│   ├── services/            # Service modules
│   │   └── JiraService.ts   # Jira API integration
│   ├── types/               # Type definitions
│   │   └── index.ts         # Schema definitions
│   └── utils/               # Utility functions
│       └── formatters.ts    # Text formatting utilities
├── build/                   # Compiled JavaScript
├── package.json             # Project dependencies
├── tsconfig.json            # TypeScript configuration
└── .env.example             # Environment variables template

テストツール

MCP Inspector を使用して、サーバーを直接テストできます。

npm run inspector

これにより、ツールの呼び出しをテストし、応答を確認できる対話型セッションが開始されます。

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加えます
4. テストとリンティングを実行します（npm run lint）
5. 変更をコミットします（git commit -m 'Add some amazing feature'）
6. ブランチにプッシュします（git push origin feature/amazing-feature）
7. プルリクエストを作成します

トラブルシューティング

よくある問題

1. 認証エラー

   • JIRA_HOST、JIRA_EMAIL、JIRA_API_TOKEN が正しいことを確認してください
   • Cloud インスタンスの場合は、API トークンが https://id.atlassian.com/manage-profile/security/api-tokens で生成されていることを確認してください

2. 権限エラー

   • API トークンに関連付けられたユーザーが Jira で適切な権限を持っていることを確認してください

3. 無効なフィールドエラー

   • 正しいフィールド ID を取得するには、list_fields ツールを使用してください
   • カスタムフィールドの形式を確認してください（単純な値ではなく、オブジェクトが必要なものもあります）

4. 接続の問題

   • Jira インスタンスへのネットワーク接続を確認してください
   • ファイアウォール設定で外部への接続が許可されていることを確認してください

5. レート制限

   • レート制限が発生した場合は、一括操作の間に遅延を追加するか、バッチサイズを小さくしてください

ライセンス

MIT

参考資料

• Model Context Protocol
• Jira REST API のドキュメント
• Jira REST API の例
• Atlassian Document Format（ADF）
• Jira クライアントライブラリ
• Zod スキーマ検証