mcp-jama

JAMA Cloud（Jama Connect）を Claude Code / Codex から操作するための MCP サーバー。 両クライアントで同じ stdio サーバーと JAMA 接続設定を利用できます。

セットアップ

Python 3.10 以上と uv が必要です。uv のインストールは 公式ガイド を参照してください。 以下のコマンド例は Bash / Zsh 向けです。

1. 設定ファイルを作成する

mkdir -p ~/.config/mcp-jama
curl -sL https://raw.githubusercontent.com/KeisukeShima/mcp-jama/main/config.json.example \
  > ~/.config/mcp-jama/config.json

~/.config/mcp-jama/config.json を編集して JAMA Cloud の接続情報を入力する。

2. 利用するクライアントに登録する

両方を使う場合は、それぞれの登録コマンドを実行します。

Claude Code

claude mcp add jama --scope user --transport stdio \
  --env "JAMA_CONFIG=$HOME/.config/mcp-jama/config.json" -- uvx mcp-jama

登録後、Claude Code のセッションを再起動します。

Codex（CLI / IDE 拡張）

codex mcp add jama \
  --env "JAMA_CONFIG=$HOME/.config/mcp-jama/config.json" -- uvx mcp-jama

Codex CLI と IDE 拡張は MCP 設定を共有します。登録後、CLI のセッションまたは IDE 拡張を再起動します。

手動で登録する場合は、~/.codex/config.toml に以下を追記します。JAMA_CONFIG は自分の設定ファイルの絶対パスに置き換えてください。 プロジェクト単位で利用する場合は、信頼済みプロジェクトの .codex/config.toml にも同じ設定を書けます。

[mcp_servers.jama]
command = "uvx"
args = ["mcp-jama"]

[mcp_servers.jama.env]
JAMA_CONFIG = "/absolute/path/to/.config/mcp-jama/config.json"

TOML 内の $HOME はシェルのようには展開されません。上記の登録コマンドではシェルが $HOME を展開し、絶対パスを保存します。

3. 接続を確認する

# Claude Code
claude mcp get jama

# Codex
codex mcp get jama

各クライアントのセッションで /mcp を開いて jama の状態を確認し、「JAMA のプロジェクト一覧を取得して」と依頼してください。 ツール一覧の取得には JAMA の認証は不要ですが、get_projects などの実行には有効な接続設定が必要です。

登録方法の詳細は Claude Code の公式ドキュメント と OpenAI Docs の Codex MCP ガイド を参照してください。

設定ファイルのパス

JAMA_CONFIG 環境変数で設定ファイルを指定します。未指定の場合は、サーバー起動時の作業ディレクトリの ./config.json を読み込みます。 ~/... の指定にも対応します。どのプロジェクトからでも使えるように、クライアントへの登録では絶対パスを指定してください。

開発者向け: ローカル実行

pip install -r requirements.txt
cp config.json.example config.json
# config.json を編集して接続情報を入力
python server.py

ローカルの変更をクライアントから検証する場合は、公開済みパッケージを使う uvx mcp-jama の代わりに、依存パッケージをインストールした Python と server.py の絶対パスを登録します。

# /absolute/path/to/python は使用する Python の絶対パスに置き換える
# python -c 'import sys; print(sys.executable)' で確認できる
claude mcp add jama-local --scope user --transport stdio \
  --env "JAMA_CONFIG=$PWD/config.json" -- \
  /absolute/path/to/python "$PWD/server.py"

codex mcp add jama-local --env "JAMA_CONFIG=$PWD/config.json" -- \
  /absolute/path/to/python "$PWD/server.py"

上記のコマンドはリポジトリ直下で実行してください。登録後はクライアントを再起動し、jama-local のツールで動作を確認します。

PyPI への公開

# 1. pyproject.toml のバージョンを上げる
# 2. 再ビルド
rm -rf dist/
hatch build
# 3. アップロード（twine は uvx 経由で実行する）
uvx twine upload dist/*
# 4. コミット・プッシュ
git add pyproject.toml
git commit -m "bump: version x.y.z"
git push

Note: twine upload を直接実行すると requests_toolbelt の依存関係エラーが出るため、uvx twine upload を使う。

テスト実行

pytest tests/

Jama への実更新を検証するテストは通常スキップされます。次のコマンドで明示的に実行できます。

JAMA_RUN_LIVE=1 JAMA_CONFIG="$HOME/.config/mcp-jama/config.json" \
  JAMA_LIVE_BASE_URL="https://<your-subdomain>.jamacloud.com" \
  JAMA_LIVE_PROJECT_ID="<test-project-id>" \
  pytest tests/test_items_live.py tests/test_tools_live.py -v -s

実行時に JAMA_LIVE_BASE_URL と JAMA_LIVE_PROJECT_ID を必ず指定してください。既定値はありません。 URL は JAMA_CONFIG の jama.base_url と一致する必要があります。プロジェクト ID には、テストデータの作成・更新・削除が許可されたプロジェクトを指定してください。 全15ツールを実 API で検証します。プロジェクト・アイテムの取得と検索、親配下への作成、フィールド更新、コメント追加、リレーション作成・取得・削除、テスト計画の作成・取得、サイクル・ランの取得、全5ステータスの結果記録が対象です。 更新後は Jama から読み直し、保存内容、未指定フィールド・配置の保持を確認します。 テスト計画・サイクル・ランには専用のテストデータを作成し、既存のアイテムやテスト結果は変更しません。 テスト管理の検証には、名前以外に追加の必須入力がない Test Case 型が必要です。型 ID は実環境から取得します。 作成したアイテム・リレーション・テスト計画・サイクル・ランは失敗時も削除を試み、削除後に取得できないことを確認します。 コメントには削除用の公開 API がないため、親のテスト用アイテムを削除し、コメント ID を出力します。コメントと操作履歴は Jama に残る場合があります。 プロセスを強制終了した場合などに残存データを確認できるよう、作成した ID を出力します。

利用可能なツール

ツール	説明
get_projects	プロジェクト一覧
get_items	アイテム一覧（ページネーション対応）
get_item	アイテム詳細
search_items	キーワード検索
create_item	アイテム作成
update_item	アイテム更新
get_relationships	トレーサビリティリンク一覧
create_relationship	リンク作成
delete_relationship	リンク削除
get_test_plans	テストプラン一覧
create_test_plan	テストプラン作成
get_test_cycles	テストサイクル一覧
get_test_runs	テストラン一覧
create_test_result	テスト結果記録
add_comment	コメント追加

認証

Basic 認証のみ対応（v1）。SSO/SAML 環境では OAuth 認証が必要になる場合があります（将来バージョンで対応予定）。

必要なライセンス: JAMA API を使用するには Named Creator ライセンス が必要です。Viewer ライセンスでは API アクセス時に 401 A named Creator license is required for access. エラーが返されます。