Jira Mcp Server

Jira MCP サーバー

シームレスな Jira Cloud 統合を実現する、包括的で本番環境に対応した Model Context Protocol（MCP）サーバーです。この拡張版では、AI エージェント、自動化システム、カスタムアプリケーション向けに、高度な機能、堅牢なエラー処理、幅広いツールを提供します。

🚀 機能

コア機能

• ボード管理：詳細情報を確認しながら、Jira ボードの一覧表示、絞り込み、管理ができます
• 課題操作：課題の作成、更新、検索、トランジション、包括的な管理ができます
• ユーザー管理：ユーザーの検索、詳細情報の取得、担当者の管理ができます
• プロジェクト管理：プロジェクトの表示と詳細情報の取得ができます
• 時間管理：柔軟な時間形式で作業ログを追加、表示できます
• コメント機能：リッチテキストに対応したコメントを追加できます（ADF 形式）
• サーバー情報：サーバーのステータスと正常性を監視できます

拡張機能

• レート制限：Jira の制限を守るため、API リクエストをインテリジェントに調整します
• 包括的なログ記録：複数のレベルに対応した、設定可能なログ機能を備えています
• エラー処理：詳細なエラーメッセージを含む、堅牢なエラー処理を行います
• 入力検証：環境変数と入力を徹底的に検証します
• モジュール式アーキテクチャ：サービスベースのアーキテクチャを採用した、すっきりと保守しやすいコードベースです
• TypeScript サポート：包括的な型定義を備えた、完全な TypeScript 実装です
• 豊富な書式設定：見やすい Markdown テーブルと書式設定済みの応答を提供します
• 高度な検索：便利な例とともに、複雑な JQL クエリに対応しています

🛠️ 要件

• Node.js：18.0.0 以降
• Jira Cloud：Jira Cloud インスタンスへのアクセス
• API トークン：Jira API トークン（こちらで作成）

⚙️ 環境変数

.env ファイルを作成するか、以下の環境変数を設定してください。

JIRA_BASE_URL=https://your-company.atlassian.net
[email protected]
JIRA_API_TOKEN=your-jira-api-token
LOG_LEVEL=INFO  # Optional: ERROR, WARN, INFO, DEBUG

🚀 クイックスタート

オプション 1：npx を使用（推奨）

# Run directly without installation
npx @orengrinker/jira-mcp-server

# With environment variables
JIRA_BASE_URL=https://company.atlassian.net \
[email protected] \
JIRA_API_TOKEN=your-token \
npx @orengrinker/jira-mcp-server

オプション 2：Claude Desktop の設定

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@orengrinker/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

オプション 3：グローバルインストール

npm install -g @orengrinker/jira-mcp-server
jira-mcp-server

オプション 4：ローカル開発

git clone https://github.com/OrenGrinker/jira-mcp-server.git
cd jira-mcp-server
npm install
npm run build
node dist/index.js

🧰 利用可能なツール

ボードツール

• get_boards - 種類やプロジェクトによる絞り込みを指定して、すべてのボードを一覧表示します
• get_board_details - ボードの詳細情報を取得します
• get_board_issues - 高度な絞り込みオプションを指定して、ボードの課題を取得します

課題ツール

• search_issues - 柔軟なパラメーターを指定して、JQL で課題を検索します
• get_issue_details - 課題の詳細情報を取得します
• create_issue - すべてのフィールドに対応した新しい課題を作成します
• update_issue - 既存の課題を更新します
• transition_issue - 課題のステータスを変更します
• add_comment - リッチテキストに対応したコメントを追加します

ユーザーツール

• get_current_user - 認証済みユーザーの情報を取得します
• search_users - 名前、メールアドレス、ユーザー名からユーザーを検索します
• get_user_details - ユーザーの詳細情報を取得します

プロジェクトツール

• get_projects - アクセス可能なすべてのプロジェクトを一覧表示します
• get_project_details - プロジェクトの詳細情報を取得します

時間管理ツール

• add_worklog - 柔軟な形式で作業時間を記録します
• get_worklogs - 課題の作業ログを表示します

システムツール

• get_server_info - サーバーのステータスと情報を取得します

💡 使用例

Claude での自然言語コマンド

Claude Desktop の設定が完了したら、自然言語コマンドを使用できます。

"Show me all my open issues in high priority"
"Create a new bug in PROJECT-X about login issues"
"Move ticket ABC-123 to In Progress"
"Log 2 hours of work on ABC-456 for code review"
"Add a comment to ABC-789 saying the fix is deployed"
"Show me all Scrum boards for the mobile project"
"Get details for issue ABC-100 including comments and worklogs"
"List all projects I have access to"

MCP Inspector での使用

# List all boards
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  get_boards

# Search for your issues
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  search_issues \
  '{"jql": "assignee=currentUser() AND status!=Done"}'

# Create a new issue
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  create_issue \
  '{"projectKey": "PROJ", "issueType": "Task", "summary": "New task from MCP"}'

JQL クエリの例

# Your open issues
assignee = currentUser() AND status != Done

# Recent issues in a project
project = "MYPROJ" AND created >= -7d

# High priority bugs
priority = High AND issuetype = Bug

# Issues due this week
duedate >= startOfWeek() AND duedate <= endOfWeek()

# Unassigned issues in current sprint
assignee is EMPTY AND sprint in openSprints()

# Issues updated in the last 24 hours
updated >= -1d

# Epic issues with their child stories
"Epic Link" = PROJ-123 OR parent = PROJ-123

🔧 設定

Jira API トークンの取得

1. Atlassian アカウント設定に移動します
2. 「Create API token」をクリックします
3. 分かりやすい名前（例：「MCP Server」）を付けます
4. 生成されたトークンをコピーします
5. 環境変数に設定します

必要な権限

Jira ユーザーには、以下の権限が必要です。

• プロジェクトの参照権限
• 課題の作成権限（課題を作成する場合）
• 課題の編集権限（更新とトランジションを行う場合）
• 課題への作業記録権限（作業ログを記録する場合）
• コメントの追加権限

🏗️ 開発

セットアップ

git clone https://github.com/OrenGrinker/jira-mcp-server.git
cd jira-mcp-server
npm install

開発スクリプト

npm run dev          # Start development server with hot reload
npm run build        # Build for production
npm run clean        # Clean build directory
npm run start        # Start production server
npm run test         # Run tests (when available)

プロジェクト構成

src/
├── index.ts              # Main server entry point
├── jiraApiClient.ts      # Enhanced API client
├── toolRegistry.ts       # Tool registration and routing
├── types/
│   └── index.ts         # TypeScript type definitions
├── services/
│   ├── index.ts         # Service exports
│   ├── boardService.ts  # Board operations
│   ├── issueService.ts  # Issue operations
│   ├── userService.ts   # User operations
│   ├── projectService.ts # Project operations
│   ├── worklogService.ts # Worklog operations
│   └── serverService.ts  # Server operations
└── utils/
    ├── logger.ts        # Logging utility
    ├── rateLimiter.ts   # Rate limiting
    ├── validation.ts    # Input validation
    └── formatters.ts    # Response formatting

🔍 トラブルシューティング

よくある問題

1. 認証に失敗する

   • API トークンとメールアドレスが正しいことを確認してください
   • Jira のベース URL が正しいことを確認してください（クラウドの場合は .atlassian.net で終わる必要があります）
   • API トークンの有効期限が切れていないことを確認してください

2. 権限が拒否される

   • Jira ユーザーに必要な権限があることを確認してください
   • 特定の操作について、プロジェクトレベルの権限を確認してください

3. ネットワークエラー

   • Jira のベース URL にアクセスできることを確認してください
   • ファイアウォールとプロキシの設定を確認してください
   • HTTPS を使用していることを確認してください

4. レート制限

   • サーバーにはレート制限機能が組み込まれています
   • Jira のレート制限に達した場合は、しばらく待ってから再試行してください
   • 同時リクエスト数を減らすことを検討してください

デバッグモード

デバッグログを有効にします：

export LOG_LEVEL=DEBUG

🧪 テスト

# Test the server connection
JIRA_BASE_URL=https://your-company.atlassian.net \
[email protected] \
JIRA_API_TOKEN=your-token \
node dist/index.js

🤝 コントリビューション

コントリビューションを歓迎します！以下のガイドラインに従ってください：

1. リポジトリをフォークする
2. 機能ブランチを作成する：git checkout -b feature/amazing-feature
3. コーディング規約に従って変更する
4. 新しい機能のテストを追加する
5. ビルドを実行する：npm run build
6. 変更をコミットする：git commit -m 'Add amazing feature'
7. ブランチにプッシュする：git push origin feature/amazing-feature
8. プルリクエストを作成する

コーディング規約

• TypeScript のベストプラクティスに従ってください
• 意味が分かりやすい変数名と関数名を使用してください
• 公開 API には JSDoc コメントを追加してください
• Conventional Commits のメッセージ形式に従ってください
• すべてのビルドが成功することを確認してください

📊 パフォーマンス

• レート制限：組み込みのレート制限により、Jira API の制限を遵守します
• コネクションプーリング：効率的な HTTP 接続管理
• エラー復旧：一時的な障害に対する自動再試行ロジック
• メモリ効率：大規模なデータセットにはストリーミングレスポンスを使用します

🔐 セキュリティ

• 認証情報を保存しない：環境変数のみを使用します
• 入力検証：すべての入力を検証し、サニタイズします
• 安全なデフォルト設定：セキュリティのベストプラクティスに従います
• 監査証跡：デバッグ用の包括的なログ記録

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

🔗 リンク

• GitHub リポジトリ：https://github.com/OrenGrinker/jira-mcp-server
• NPM パッケージ：@orengrinker/jira-mcp-server
• Jira Cloud REST API：ドキュメント
• Model Context Protocol：仕様
• API トークンの作成：Atlassian ガイド

🆘 サポート

• 問題：GitHub Issues
• ドキュメント：この README とインラインコードのドキュメントをご確認ください
• 機能リクエスト：「enhancement」ラベルを付けて Issue を作成してください

🏆 謝辞

• Model Context Protocol SDK を使用して構築されています
• MCP コミュニティとベストプラクティスに着想を得ています
• フィードバックを寄せてくださったすべてのコントリビューターとユーザーに感謝します