jira-mini-mcp

jira-mini-mcp

コーディングエージェント向けの Jira Cloud MCP サーバーです。読み取りツールは6個、書き込みを有効にすると9個です。

一つの仕事に、一つのツール。確実に。

汎用の Atlassian MCP サーバーには、数十から数百ものツールがあります。エージェントが有用な作業を始める前から、その一つひとつがコンテキストを消費し、よく似たツールが増えるほど、エージェントはどれを選ぶべきか迷います。このサーバーがコーディングエージェントに提供するのは、チケットに必要な Jira のコンテキストと、結果を返すための3つの方法だけです。それ以外は提供しません。

• 98個ではなく、6～9個のツール - すべてがコンテキストに含める価値を備えており、エージェントが適切なツールを選べるよう説明もテスト済みです。ツールを絞っている理由と代替手段との比較をご覧ください。
• 書き込み操作は3つのツールだけ - コメント、トランジション、更新です。READ_ONLY_MODE=trueにすると、無効な項目としてエージェントに表示されることすらなく、登録されません。
• 簡潔で予測可能な出力 - 安定した JSON スキーマ、リッチテキストには Markdown を使用し、nullの羅列やself URL、メールアドレス、アバターは含みません。ツールの返却内容をご覧ください。
• 通信量を約40％削減 - 各結果はstructuredContentとして重複して送信されることなく、content内の JSON として一度だけ送信されます。ホストで型付きのコピーが必要な場合は、STRUCTURED_OUTPUT=trueを設定してください。出力コストの削減をご覧ください。
• 結果を黙って途中で切り上げません - コメントと変更履歴の正確な総数、検索のカーソルページングに対応し、残りを取得するにはlimit=0を指定できます。リクエストが失敗した場合はエラーを返し、空のリストにはしません。
• エージェントが対処できるエラー - トランジション名が間違っている場合、利用可能なすべてのトランジションと遷移先を表示するため、別途確認用のツールは不要です。エラーに Jira の URL、認証情報、生のレスポンス本文が含まれることはありません。
• API トークンまたは OAuth - API トークンなら1分で設定でき、独自の OAuth 2.0 アプリを使えばブラウザーでログインでき、自動更新にも対応します。設定をご覧ください。
• PyPI で公開 - uvx jira-mini-mcpまたはpip install jira-mini-mcpで利用できます。リポジトリのクローンや Git URL は不要です。

ヒント

READ_ONLY_MODE=true を設定すると、6 つの 🟢 読み取りツールのみが登録され、 3 つの 🔴 書き込みツールは完全に利用できなくなります。詳しくは設定をご覧ください。

• インストール
• 設定
• Jira への書き込み
• ツールが少ない理由
• 他の選択肢との比較
• コントリビューションとセキュリティ

詳しくはdocs/をご覧ください：設定、 OAuth の設定、およびツールの返却内容と 例。

インストール

uvx jira-mini-mcp

または

pip install jira-mini-mcp

固定された仕様で使う場合は、バージョンを固定してください：uvx jira-mini-mcp==1.1.0。

未リリースのコミットを GitHub から直接実行することもできます：

uvx --from git+https://github.com/proprock/jira-mini-mcp jira-mini-mcp

Python 3.12 以降とuv（またはpip）が必要です。

設定

API トークンを使う場合は、次の 3 つの値を設定します：

書き込みツールを利用できないようにするには、READ_ONLY_MODE=true を追加します。 STRUCTURED_OUTPUT を含むすべての設定については、configuration.mdをご覧ください。

メモ

トークンを保存するより OAuth を使いたい場合：JIRA_AUTH_METHOD=oauth を設定し、 無料の OAuth 2.0（3LO）アプリを登録してから、jira-mini-mcp login を一度実行して ブラウザーで認証します。その後、サーバーが自動的にトークンを更新します。手順については、 oauth.mdをご覧ください。

設定は起動時に検証されます。エラーには不足している設定が示されますが、その値や Jira の URL は表示されません。トークンはホスト側の設定に保存し、決してコミットしないでください。サーバーはあなたのアカウントの権限で動作します。課題をトランジションできないアカウントでは、このサーバーがどの機能を公開していても課題をトランジションできません。

claude mcp add --env JIRA_BASE_URL=https://example.atlassian.net --env [email protected] --env JIRA_API_TOKEN=your-token --transport stdio jira-mini -- uvx jira-mini-mcp

{
  "mcpServers": {
    "jira-mini": {
      "command": "uvx",
      "args": ["jira-mini-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://example.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-token"
      }
    }
  }
}

codex mcp add jira-mini --env JIRA_BASE_URL=https://example.atlassian.net --env [email protected] --env JIRA_API_TOKEN=your-token -- uvx jira-mini-mcp

エージェントが作業したチケットを最後まで処理できるように選んだ、3 つのツールです。

add_comment(issue_key, body)
transition_issue(issue_key, to, comment=None)
update_issue(issue_key, fields)

課題の作成、リンク、添付ファイルのアップロード、作業ログ、削除は対象外です。作成には、プロジェクトと課題タイプごとに必須フィールドを特定する必要があり、それ自体が独立した機能となります。リンクを追加する場合も、追加を依頼する場合も、コメントで対応できます。

エージェントが書き込む前に知っておくべきことが 3 つあります。

• transition_issue で指定するのは ID ではなく名前です。 大文字と小文字を区別せず、トランジション名または遷移先ステータス名で照合します。実際のワークフローでは両者が異なることがあります。たとえば、In Progress というトランジションによって In Development というステータスになったり、名前の異なる 2 つのトランジションが同じステータスに到達したりすることがあります。そのため、トランジション名を優先してください。一致するものがない場合、エラーには利用可能なすべてのトランジションと、その遷移先が表示されます。先に選択肢を確認するには、get_issue(fields=["transitions"]) を指定します。そのため、個別の get_transitions ツールはありません。
• update_issue は labels と components を一括で置き換えます。 追加または削除する動詞はないため、値を 1 つ追加する場合は、先に課題を読み取ってください。get_issue が返す値と同じものを受け取ります。assignee はアカウント ID、メールアドレス、表示名、または文字列リテラルの "me"、description は Markdown、customfield_* は Jira の生 JSON です。status と comment は受け付けず、それぞれを処理するツール名を示します。
• Markdown は推測せずに変換されます。 見出し、リスト、フェンス付きコード、インラインの書式、リンクは Jira のリッチテキストに変換され、それ以外は再解釈せず、そのまま保持されます。

各書き込みツールには、readOnlyHint=false と、実態に即した destructiveHint および idempotentHint の値が付与されています。READ_ONLY_MODE がフィルタリングに使うのはこれらの値です。

ツールが少ない理由

ツール定義は、名前、説明、入力スキーマ、そして多くの場合は出力契約で構成されます。クライアントによっては、作業が始まる前に、そのすべてがモデルのコンテキストに入ります。そのため、ツールセットが大きいと、現在のタスクでは使わない機能にコンテキストを費やし、ツールの選択ミスや、似たツールの混同、不適切なパラメーターの指定につながる可能性が高まります。

コンパクトなスキーマを 6〜9 個に抑えれば、セッション全体を通じて無理なく利用でき、ソースコード、課題の説明、スタックトレース、推論のためにコンテキストの予算を確保できます。この設計は、エージェントシステムに関する Anthropic のガイダンスに従っています。ツールセットは小さく、役割を限定し、明確に差別化します。

これは主張であるため、リポジトリで検証しています。オフラインのテストでは、各ツールの説明が十分に記述されていること、説明同士が酷似していないこと、名前から動作を推測できないパラメーターについては、すべて説明文で補足されていることを確認します。もう一方では、実際のツール定義を実際のモデルに提示し、モデルがどのツールを選ぶかを評価します。詳しくは evals/README.md をご覧ください。

同じ原則はレスポンスにも反映されています。get_issue は、数百件のコメント、変更履歴の全件、添付ファイルの内容、すべてのカスタムフィールドを一度に出力しません。大きなリソースは、要求された場合にのみ取得します。

代替手段との比較

Atlassian 製品全般を幅広く使いたい場合、独自アプリを登録せずに OAuth を使いたい場合、Jira Service Management が必要な場合、または権限グループ、IP 許可リスト、監査ログなどの組織レベルの管理機能が必要な場合は、公式サーバーがより適しています。 Atlassian 自身の製品であり、同社の API に追従しています。このサーバーがそれに対抗するものではありません。

Jira と合わせて Confluence も必要な場合、Server/Data Center を使う場合、または 6～9 個のツールよりも幅広い Jira 対応が必要な場合は、mcp-atlassian がより適しています。

このサーバーがより適しているのは、対象を絞った次のケースです。Jira チケットに取り組むコーディングエージェントで、各ツール定義にかかるコンテキストのコストが、対応範囲の広さよりも重要な場合です。

貢献とセキュリティ

セットアップ、チェック、テストと評価のコマンド、ブランチとコミットの規約、リリースモデルについては、CONTRIBUTING.md をご覧ください。SECURITY.md の説明に従って、脆弱性を非公開で報告してください。サーバーを実行するユーザーに影響する変更は、CHANGELOG.md に記録されています。

ライセンス

MIT。Atlassian の公式製品ではありません。