Jira MCP サーバー

Jiraと連携するためのツールを提供するModel Context Protocol (MCP) サーバーです。Cursorやその他のMCPクライアントが、チケットの取得、リンクされたチケットの管理、チケットステータスの更新を行えるようにします。

クイックスタート

1. 依存関係のインストール

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

2. Jira認証情報の設定

推奨: パーソナルアクセストークン (PAT)

1. Jiraにログイン: https://jira.telekom.de

2. プロフィール > パーソナルアクセストークン に移動

3. 「トークンを作成」をクリック

4. 名前（例: "Cursor MCP"）を付け、有効期限を設定

5. 重要: トークンに 「読み取り」 または 「プロジェクトの閲覧」 権限があることを確認してください

6. トークンをすぐにコピーしてください（二度と表示されません）

.env ファイルを作成:

cp .env.example .env

.env を編集して認証情報を入力:

JIRA_URL=https://jira.telekom.de
JIRA_USERNAME=your.username@telekom.de
JIRA_API_TOKEN=your_personal_access_token_here
JIRA_AUTH_TYPE=bearer

注意: Kantega SSO APIトークンにはIP制限がある場合や、管理者が設定した権限が必要な場合があります。ほとんどのユーザーにはパーソナルアクセストークンが推奨されます。

3. Cursorでの設定

1. Cursorを開く

2. Settings > Tools and MCP に移動

3. 以下の設定を追加:

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jira-mcp",
        "run",
        "-m",
        "src"
      ]
    }
  }
}

重要: パスと認証情報は実際の値に置き換えてください！

4. Cursorを完全に再起動

4. 試してみる

Cursorのチャットで以下を試してください:

• "Get details for Jira ticket PROJ-123"

• "Show me all linked tickets for PROJ-456"

• "Update PROJ-789 status to In Progress"

機能

利用可能なツール

認証サポート

• Bearerトークン: パーソナルアクセストークン (PAT) - 推奨

• 基本認証: ユーザー名 + APIトークン (Atlassian Cloud)

• Cookie認証: セッションベースの認証 (フォールバックオプション)

ツールの詳細

get_ticket

チケットの完全な情報を取得します。

パラメータ:

• ticket_id (string, 必須): チケットIDまたはキー (例: "PROJ-123")

戻り値:

{
  "key": "PROJ-123",
  "summary": "Ticket summary",
  "description": "Detailed description",
  "status": "In Progress",
  "issue_type": "Story",
  "priority": "High",
  "assignee": "John Doe",
  "reporter": "Jane Smith",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-20T14:45:00.000+0000",
  "comments_count": 3,
  "comments": [...],
  "custom_fields": {...}
}

get_linked_tickets

関連するすべてのチケットとサブタスクを取得します。

パラメータ:

• ticket_id (string, 必須): チケットIDまたはキー

戻り値:

{
  "ticket": "PROJ-123",
  "linked_tickets": [
    {
      "link_type": "Blocks",
      "direction": "blocks",
      "key": "PROJ-124",
      "summary": "Related ticket",
      "status": "To Do"
    }
  ],
  "linked_tickets_count": 1,
  "subtasks": [...],
  "subtasks_count": 2
}

update_ticket_status

ワークフローの検証を行いながらチケットのステータスを更新します。

パラメータ:

• ticket_id (string, 必須): チケットIDまたはキー

• status (string, 必須): ターゲットステータス (例: "In Progress", "Done")

戻り値:

Successfully updated ticket PROJ-123 status from 'To Do' to 'In Progress'

注意: このツールは遷移を検証します。無効な場合は、利用可能な遷移を返します。

テスト

テストの実行

# Run all tests
.venv/bin/pytest tests/ -v

# Run with coverage
.venv/bin/pytest tests/ --cov=src -v

# Run specific test file
.venv/bin/pytest tests/test_integration/test_real_tickets.py -v

手動テスト

サーバーを直接テスト:

uv run --env-file .env -m src

Ctrl+Cを押して停止します。

トラブルシューティング

認証エラー

症状: "401 Unauthorized" または "403 Forbidden"

解決策:

• 最も一般的: パーソナルアクセストークンの有効期限切れ - 新しいものを生成してください

• PATに「読み取り」または「プロジェクトの閲覧」権限があることを確認

• ユーザー名がJiraアカウントのメールアドレスと一致していることを確認

• JIRA_URL に https:// が含まれていることを確認

• パーソナルアクセストークンの場合、JIRA_AUTH_TYPE=bearer であることを確認

チケットが見つからない

症状: "404 Not Found"

解決策:

• チケットキーが正しいか確認 (例: "PROJ-123")

• チケットを表示する権限があるか確認

• 正しいJiraインスタンスを使用しているか確認

Cursorにサーバーが表示されない

解決策:

• MCP設定の絶対パスを確認

• Python 3.12+ がインストールされているか確認: python3 --version

• Cursorを完全に再起動 (終了して再度開く)

• Cursorの開発者コンソールでエラーを確認

チケットを遷移できない

症状: "Invalid status transition"

解決策:

• エラーメッセージに利用可能な遷移がリストされます

• ステータス名は正確に一致する必要があります (大文字小文字を区別)

• Jiraのワークフロー権限を確認

• ワークフローに対して遷移が有効であることを確認

アーキテクチャ

このプロジェクトはSOLID原則とクリーンアーキテクチャに従っています:

src/
├── __init__.py
├── __main__.py           # Entry point
├── server.py             # MCP server setup
├── config/               # Configuration management
├── client/               # Jira API client
├── tools/                # 3 MCP tools
├── models/               # Domain models
├── mappers/              # Data transformation
└── utils/                # Error handling, JSON utils

主要原則:

• SOLID: 単一責任、依存性逆転

• DRY: 重複なし、再利用可能なコンポーネント

• 型安全性: 全体を通して完全な型ヒント

• テスト容易性: 関心の明確な分離

詳細な技術ドキュメントについては ARCHITECTURE.md を参照してください。

開発

プロジェクト構造

jira-mcp/
├── src/                  # Source code (22 Python files)
├── tests/                # Test suite
├── pyproject.toml        # Project config (includes pytest config)
├── .env.example          # Config template
├── .gitignore
├── README.md             # This file
└── ARCHITECTURE.md       # Technical docs

依存関係の追加

uv add package-name

異なる設定での実行

uv run --env-file .env.production -m src

コード品質

• Lintエラー: 0

• 型カバレッジ: 100%

• テストカバレッジ: 3つのツールすべてに対する統合テスト

• アーキテクチャ: SOLID + DRY準拠

要件

• Python 3.12+

• APIアクセス権を持つJiraアカウント

• Jira APIトークン (Kantega SSO Enterprise または Atlassian Cloud)

ライセンス

このプロジェクトは、CursorおよびJiraで使用するために現状のまま提供されます。

SOLIDおよびDRY原則に従ったベストプラクティスで構築されています 🚀