Jira MCP サーバー（読み取り専用）

Claude Code が Jira のチケットコンテキスト（課題の詳細、コメントスレッド、チケット周辺の参照グラフ、JQL 検索結果）をコンパクトな Markdown として取得できるローカル MCP サーバーです。画像添付ファイル（例：UI バグチケットのスクリーンショット）は、Claude が視覚的に分析できるように取得できます。

意図的にできないこと

このサーバーは厳密に読み取り専用です。何かを作成、更新、遷移、削除、コメントするツールは一切公開していません。強制は多層的に行われます。

1. コード内: すべての HTTP リクエストは単一のヘルパーを通り、GET のみ許可されます。唯一の許可リスト例外は POST /rest/api/3/search/jql で、これは Atlassian が POST での送信を要求する読み取り操作です。他のメソッドは ReadOnlyViolationError を発生させるため、将来書き込み呼び出しを追加する編集があれば、明確に失敗します。

2. 資格情報レベル: API トークンを読み取りスコープのみで作成します（下記参照）。これにより、バグがあっても書き込みはできません。

Related MCP server: JIRA MCP Server

ツール

セットアップ

1. Atlassian API トークンを作成

1. https://id.atlassian.com/manage-profile/security/api-tokens に移動します。

2. スコープ付き API トークンを作成 を選択します（Atlassian はスコープなしトークンを廃止予定です）。

3. Jira アプリを選択し、以下のスコープのみを選択します：

   • read:jira-work

   • read:jira-user

4. トークンをすぐにコピーします。一度しか表示されません。

古いスコープなしトークンも機能します。サーバーは両方を自動的に処理します（下記参照）。

2. .env を設定

cp .env.example .env   # then edit

必須キー（これが設定の全表面です）：

.env は gitignore されています。絶対にコミットしないでください。実際の環境変数はファイルより優先されます。ファイルはプロジェクトディレクトリ（作業ディレクトリではなく）を基準に配置されるため、サーバーはどこから起動しても見つけられます。

3. 依存関係をインストール

uv を使用（このリポジトリには uv.lock があるため推奨）：

uv sync

または、venv に通常の pip を使用：

python -m venv .venv
.venv/bin/pip install -r requirements.txt   # Windows: .venv\Scripts\pip

4. --check で確認

.venv/bin/python -m jira_mcp --check            # connectivity + auth only
.venv/bin/python -m jira_mcp --check PROJ-123   # also fetch a ticket in full

これにより、.env が見つかったか、選択されたベース URL（およびクラウド ID フォールバックが必要かどうか）、認証されたアカウント、そしてキーが指定された場合は Claude が表示するのとまったく同じチケットが出力されます。

スコープ付き vs. スコープなしトークン：ベース URL の問題

• スコープなしトークンは、サイト URL https://<site>.atlassian.net に対して機能します。

• スコープ付きトークンは同じ URL に対して静かに失敗し、匿名のような応答を返します。代わりに https://api.atlassian.com/ex/jira/{cloudId} を呼び出す必要があります。

どちらの種類を持っているかを知る必要はありません。起動時にサーバーは GET /rest/api/3/myself でサイト URL をプローブします。実際のアカウントが返されない場合は、{site}/_edge/tenant_info からクラウド ID を取得し、api.atlassian.com に対して再試行します。勝者はプロセス存続期間中キャッシュされ、stderr にログ出力されます。

検出が失敗した場合：_edge/tenant_info は Atlassian の正式にサポートされた REST API の一部ではありません（ただし、Atlassian 自身のサポートドキュメントはそれを指しています）。変更される可能性があります。その場合は、.env に ATLASSIAN_CLOUD_ID を設定して検出をスキップします。エラーメッセージが適用時期を示します。ほとんど必要ありません。

PyCharm セットアップ

1. インタープリター: Settings → Project → Python Interpreter → Add Interpreter → Existing → プロジェクトディレクトリ内の .venv/bin/python を選択します。（uv sync を実行した場合、venv はすべてインストール済みで既に存在します。）

2. デバッグ用の実行構成: Run → Edit Configurations → + → Python：

   • Run: モジュール jira_mcp（「スクリプトパス」ではなく「モジュール」を選択）

   • Parameters: --check PROJ-123

   • Working directory: プロジェクトルート（何でも機能しますが、これがきれいです）

   これで、どこにでもブレークポイントを設定（例：client.py 内）し、実際のリクエストをデバッグできます。実行中の MCP サーバー内のエラーは、それ以外では見えません。

Claude Code に接続

venv の Python を絶対パスで使用します。裸の python では、Claude Code がサーバーを起動するときに venv に解決されません。

macOS/Linux：

claude mcp add jira -- /path/to/PythonProject/.venv/bin/python -m jira_mcp

Windows：

claude mcp add jira -- C:\path\to\PythonProject\.venv\Scripts\python.exe -m jira_mcp

注意：

• -- の後はすべて Claude が実行するコマンドです。-- の前はすべて Claude 自身のオプションです。

• デフォルトのスコープは local（自分だけ、このプロジェクトだけ、~/.claude.json に保存）です。--scope project を追加してチェックインされた .mcp.json で共有するか、--scope user を追加してすべてのプロジェクトで使用します。

接続を確認

Claude Code セッション内で：

• /mcp を実行します。jira サーバーが接続済みとして、6 つのツールとともに一覧表示されるはずです。

• または、単に尋ねます：「whoami を使って jira 接続を確認して」。

トラブルシューティング

Python 初心者向けの開発者向けメモ

• venv（.venv/）は、このプロジェクトのパッケージに加えて Python のプロジェクトローカルコピーです。node_modules に相当しますが、インタープリター自体もその中に含まれます。そのため、Claude Code には .venv/bin/python を絶対パスで指定する必要があります。フォールバックできるグローバルインストールはありません。

• asyncio.run(...) が必要なのは、Python の非同期関数は呼び出しただけでは実行されないためです。呼び出すとコルーチンオブジェクトが返され、それを駆動する何かが必要です。Node のような環境イベントループはありません。asyncio.run() はループを作成し、1 つのコルーチンを完了まで実行し、ループを破棄します。MCP サーバーはこれを mcp.run() 経由で内部的に行います。--check モードは明示的に行います。

• デコレータ（@mcp.tool）は、その下で定義された関数を受け取り、登録/ラップする関数です。定義時に適用されるミドルウェアファクトリのようなものです。FastMCP のデコレータは、関数の名前、型ヒント、docstring を読み取り、Claude が表示する MCP ツールスキーマを生成します。docstring はツールの API ドキュメントそのものです。

• python -m jira_mcp はパッケージの __main__.py を実行します。これは Python で npm の bin エントリに最も近いものです。uv sync がプロジェクトを venv にインストールしたため、どのディレクトリからでも機能します。