mcp-gitlab

mcp-gitlab

mcp-gitlab は、GitLab REST API 向けの Model Context Protocol（MCP） サーバーです。AI アシスタントに 91 個のツール、7 個のリソース、6 個のプロンプトを提供し、プロジェクト、マージリクエスト、パイプライン、CI/CD 変数、承認、イシュー、コードレビューを管理できます。Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot、および MCP 対応クライアントで利用できます。書き込み可能モード、または読み取り専用にロックされたモード（MCP_READ_ONLY=true）のどちらかで実行でき、後者では 57 個の書き込みツールがモデルに提示されることはありません。

GitLab.com とセルフホスト型 GitLab インスタンス（CE/EE）に対応しています。GitLab Duo や Premium は不要です。

MCP 2026-07-28 仕様（MCP 2.0 と呼ばれることもあります）に対応し、2025-11-25 クライアントとの互換性も維持しています。

FastMCP 4.x、httpx、Pydantic で構築されています。

インストール： uvx mcp-gitlab | PyPI | MCP Registry | 変更履歴

uvx mcp-gitlab                          # with writes
MCP_READ_ONLY=true uvx mcp-gitlab       # locked read-only: write tools are not listed

ワンクリックインストール

💡 ヒント： その他の AI アシスタント（Claude Code、Windsurf、IntelliJ、Gemini CLI）については、GitLab MCP Installation Gateway をご覧ください。

# with writes
claude mcp add gitlab -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab
# locked read-only
claude mcp add gitlab -e MCP_READ_ONLY=true -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab

{
  "mcpServers": {
    "gitlab": {
      "command": "uvx",
      "args": ["mcp-gitlab"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
gemini mcp add -s user -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab uvx mcp-gitlab
# locked read-only
gemini mcp add -s user -e MCP_READ_ONLY=true -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab uvx mcp-gitlab

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-gitlab"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
codex mcp add gitlab --env GITLAB_URL=https://gitlab.example.com --env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab
# locked read-only
codex mcp add gitlab --env MCP_READ_ONLY=true --env GITLAB_URL=https://gitlab.example.com --env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab

uv pip install mcp-gitlab

サポートされているトークンの種類

サーバーは以下の環境変数を順に確認し、最初に一致したものを使用します。

1. GITLAB_TOKEN
2. GITLAB_PAT
3. GITLAB_PERSONAL_ACCESS_TOKEN
4. GITLAB_API_TOKEN

以下のいずれかの種類のトークンを指定できます。

トークンなしでサインインする

stdio 経由で自分用にサーバーを実行し、パーソナルアクセストークンがない場合に使用します。mcp-gitlab auth login を実行すると、パブリック OAuth クライアントとして GitLab にサインインし、トークンをローカルに保存します。以降、サーバーは起動時にトークンを読み込み、自動で更新します。これは OAuth モードではありません。サーバーはトークンモードのままで、MCP ワイヤ上の動作に変更はありません。

コマンドは 3 つです。

mcp-gitlab auth login     # device flow by default; add --web for the browser flow
mcp-gitlab auth status    # show the stored account, scopes, and token freshness
mcp-gitlab auth logout    # revoke the token at GitLab and delete the local copy

auth login を実行すると、コードと URL が表示されます。URL を開いてコードを入力し、承認してください。その後、GITLAB_URL を設定し、トークンを指定しなくてもサーバーを使用できます。

クライアント ID

サインインのたびに OAuth アプリケーション ID が必要です。解決順序は --client-id、GITLAB_OAUTH_CLIENT_ID、https://gitlab.com 用の組み込みデフォルトです。

gitlab.com のデフォルトは、まだ登録されていません。登録されるまでは、gitlab.com でも GITLAB_OAUTH_CLIENT_ID を設定するか、--client-id を指定してください。

アプリを登録する（セルフマネージド環境、またはデフォルトが提供されるまでの gitlab.com）

User Settings → Applications → Add new application で、以下の設定を使ってアプリケーションを作成します。

localhost ではなく 127.0.0.1 を使用してください。デバイスフローには GitLab 17.9 以降が必要です。それより古いインスタンスでは mcp-gitlab auth login --web を使用してください。

保存場所と優先順位

認証情報は ~/.config/mcp-gitlab/credentials.json に、GitLab URL ごとに 1 件ずつ、モード 0600 で保存されます。環境変数のトークンが常に優先されます。GITLAB_TOKEN が設定されている場合、サーバーはその値を使用し、保存済みの認証情報は無視します。

読み取り専用セッションにするには --scopes read_api を指定してください。この場合、サーバーは API 呼び出しの前に書き込みツールをブロックします。

OAuth 2.1（リモートデプロイ）

複数人で共有するサーバーでは、--auth oauth を指定すると、GitLab を上流の OAuth プロバイダーとする MCP 2026-07-28 リソースサーバーとして mcp-gitlab が動作します。各ユーザーはそれぞれの GitLab アカウントでサインインし、すべてのリクエストはそのユーザーのトークンで実行されるため、サーバーにパーソナルアクセストークンを設定する必要はありません。サーバーを一度ホストし、複数のユーザーが接続する場合に使用してください。単一ユーザーのローカル環境では、デフォルトの --auth token を使用してください。

OAuth モードには --transport streamable-http が必要です（OAuth は HTTP にのみ適用されます。stdio では引き続き環境トークンが使用されます）。

1. GitLab OAuth アプリケーションを登録する（ユーザー設定 → アプリケーション、またはグループ／インスタンスのアプリケーション）。リダイレクト URI を <base>/auth/callback（例：https://mcp.example.com/auth/callback）に設定し、機密情報としてマークして、api スコープ（読み取り専用のデプロイでは read_api）を許可します。Application ID と Secret をコピーします。

2. サーバーを設定する：

GITLAB_URL=https://gitlab.com GITLAB_AUTH=oauth \
  GITLAB_OAUTH_CLIENT_ID=... GITLAB_OAUTH_CLIENT_SECRET=... \
  GITLAB_OAUTH_BASE_URL=https://mcp.example.com \
  uvx mcp-gitlab --transport streamable-http

MCP クライアント（または MCP Inspector、pnpm dlx @modelcontextprotocol/inspector）から <base>/mcp に接続すると、認可サーバーを検出して OAuth フローを実行します。その後、各ツール呼び出しでは、そのユーザーの GitLab トークンが使用されます。read_api のみのトークンでは読み取りはできますが、実行可能な対応策を示すヒントとともに書き込みが拒否されます。

詳しいガイド、クライアントの設定、トラブルシューティングについては、docs/oauth.md をご覧ください。

互換性

プロトコルのサポート

mcp-gitlab は Model Context Protocol を実装しています。MCP 2.0 とも呼ばれる 2026-07-28 仕様をサポートしています。2025-11-25 クライアントとの互換性も維持しています。

• 仕様：MCP 2026-07-28（MCP 2.0）。stdio と streamable-http で検証済みです。
• レガシークライアント：2025-11-25 クライアントも引き続き動作します。
• 基盤：FastMCP 4.x と MCP Python SDK 2.x。
• トランスポート：stdio（デフォルト）と streamable-http（リモート接続に推奨）。sse（HTTP+SSE）トランスポートも引き続き動作しますが、2026-07-28 仕様では非推奨になっています。使用するとサーバーが警告を表示します。
• 機能：ツール、リソース、プロンプト。サーバーはルート、サンプリング、ログ記録、エリシテーション、リソースサブスクリプションを使用しないため、2026-07-28 での非推奨化の影響はありません。

エラー結果

予期される失敗（404、401、検証エラー、または読み取り専用ガードに阻止された書き込み）は、プロトコルレベルの isError フラグが設定されたツール結果として返されるため、クライアントは正常に見える結果から "error" キーを解析するのではなく、失敗を検出して自己修正できます。ロックされた読み取り専用モードでは書き込みツールが非表示になるため、呼び出すと Unknown tool エラーが返されます。読み取り専用エンベロープはガード自体の応答であり、クライアントが何らかの理由で書き込みツールに到達した場合（キャッシュされた一覧、または将来タグ付けされていないツール）にのみ返されます。本文は error と、役立つ場合は status_code、body、および実行可能な hint を含む JSON オブジェクトです。このオブジェクトが結果のテキストコンテンツになります。厳格なクライアント（TypeScript MCP SDK）は isError の結果でも structuredContent をツールの出力スキーマに照らして検証し、そのスキーマはエラー本文を拒否するため、エラー結果には structuredContent は設定されません。予期しないバグも isError の結果として返されますが、TypeName: message のテキストのみを含み、同様に structuredContent はありません。

成功した結果では、レスポンスは整形済みのテキストコンテンツと structuredContent の両方で JSON オブジェクトとして返されます（オブジェクトそのものであり、厳格なクライアントが拒否する旧形式の {"result": "<json string>"} ラッパーではありません）。ツールは outputSchema を公開しません。上流の GitLab フィールドは型指定されずにそのまま渡されるため、新しい API フィールドがスキーマに影響することはありません。クライアントが型指定されたスキーマを必要とする場合は、ツールごとに output_schema= を指定してオプトインできます。

ツール（91）

リソース（7）

このサーバーは、クライアントが必要に応じて読み取れる、厳選されたワークフローガイドをMCP リソースとして公開します。

プロンプト（6）

このサーバーは、クライアントがスラッシュコマンドとして表示できる、再利用可能な複数ツールのワークフローテンプレートであるMCP プロンプトを提供します。

使用例

プロジェクトとブランチ

"Get details for project my-org/api-gateway"
→ gitlab_get_project(project_id="my-org/api-gateway")

"Create a feature branch from main"
→ gitlab_create_branch(project_id="123", branch_name="feat/login", ref="main")

"Delete all branches merged into main"
→ gitlab_list_branches(project_id="123") → filter merged → gitlab_delete_branch for each

マージリクエストとコードレビュー

"Open a merge request from feat/login to main"
→ gitlab_create_mr(project_id="123", source_branch="feat/login", target_branch="main", title="Add login")

"Review MR !42 — list changes and add inline comments"
→ gitlab_mr_changes(project_id="123", mr_iid=42)
→ gitlab_create_mr_discussion(project_id="123", mr_iid=42, body="nit: ...", new_path="src/auth.py", new_line=15)
  # old_line is filled from the diff when line 15 is unchanged

"Merge MR !42 after resolving all threads"
→ gitlab_list_mr_discussions(project_id="123", mr_iid=42) → resolve unresolved
→ gitlab_merge_mr(project_id="123", mr_iid=42, squash=True)

パイプラインと CI/CD

"Show failed pipelines on main this week"
→ gitlab_list_pipelines(project_id="123", ref="main", status="failed")

"Retry a failed pipeline"
→ gitlab_retry_pipeline(project_id="123", pipeline_id=456)

"Get the build log for job 789"
→ gitlab_get_job_log(project_id="123", job_id=789, tail_lines=100)

イシュー

"Create a bug report in project 123"
→ gitlab_create_issue(project_id="123", title="Login page 500 error", labels=["bug","P1"])

"Find open issues assigned to me"
→ gitlab_list_issues(project_id="123", state="opened", assignee_username="johndoe")

セキュリティに関する考慮事項

• トークンのスコープ：必要最小限のスコープを使用してください。api スコープはすべてのアクセスを許可するため、読み取り専用のデプロイでは read_api を推奨します。
• 読み取り専用モード：起動を管理する場所で MCP_READ_ONLY=true（または GITLAB_READ_ONLY=true）を設定すると、サーバーはロックされた状態で起動します。57 個の書き込みツールと書き込みワークフローのプロンプトは一覧に表示されず、それらを呼び出すと「Unknown tool」が返され、ガードはそれでも到達した書き込みを拒否します。実行時にロックを解除するものはありません。別のソースからの false、.env ファイル、ツール引数のいずれも解除できません。false／0／no／off／空以外の値はすべてロックし、--read-only はロックを強めることしかできません。ロックの強度は起動方法に依存します。ユーザーが編集できない場所（Claude Code の managed-mcp.json などの管理対象 MCP 設定、コンテナ、k8s または systemd の環境変数、ホスト型 HTTP デプロイなど）で設定してください。サーバーを自分で起動するユーザーは、その環境を制御できます。OAuth モードでは、各ユーザーの GitLab トークンに書き込みスコープが含まれないよう、GITLAB_OAUTH_SCOPES=read_api も設定してください。
• SSL 検証：デフォルトでは GITLAB_SSL_VERIFY=true です。信頼できるネットワーク内で自己署名証明書を使用する場合に限り、無効にしてください。
• CI/CD 変数のマスキング：gitlab_list_variables と gitlab_list_group_variables は、GitLab でマスク対象として設定された変数の値を自動的にマスクし、実際の値の代わりに ***MASKED*** を返します。
• MCP ツールのアノテーション：各ツールは、クライアント側の権限確認プロンプト用に readOnlyHint、destructiveHint、idempotentHint を宣言します。
• 認証情報の保存：サーバーは環境変数から GITLAB_TOKEN を読み込み、書き込むことはありません。mcp-gitlab auth login は OAuth トークンを ~/.config/mcp-gitlab/credentials.json に保存し（モード 0600）、その場で更新します。

レート制限と権限

レート制限

GitLab はユーザーごとのレート制限を適用します（デフォルトでは、認証済みユーザーは 1 分あたり 2000 リクエストです）。レート制限に達すると、ツールは再試行まで待つよう案内するヒント付きの 429 エラーを返します。ページネーション対応エンドポイントのデフォルトは 1 ページあたり 20 件です。API 呼び出し回数を減らすには、per_page（最大 100）を使用してください。

必要な権限

CLI とトランスポートのオプション

# Default: stdio transport (for MCP clients)
uvx mcp-gitlab

# HTTP transport — streamable-http is recommended for remote use
uvx mcp-gitlab --transport streamable-http --port 9000

# SSE transport — deprecated by MCP 2026-07-28; still works, prints a warning
uvx mcp-gitlab --transport sse --host 127.0.0.1 --port 8000

# OAuth 2.1 mode (per-user GitLab sign-in; streamable-http only) — see "OAuth 2.1" above
uvx mcp-gitlab --auth oauth --transport streamable-http

# Local sign-in for stdio without a token — see "Sign in without a token" above
mcp-gitlab auth login|status|logout

# CLI overrides for config
GITLAB_TOKEN=glpat-xxx uvx mcp-gitlab --gitlab-url https://gitlab.example.com --read-only

--gitlab-token は引き続き使用できますが、非推奨であり、--help には表示されません。トークンが ps とシェルの履歴に残るためです。GITLAB_TOKEN を使用してください。

--auth {token,oauth} は認証モードを選択します（デフォルトは token）。 oauth には --transport streamable-http が必要です。

トークンモードでは、HTTP トランスポートは単一の GITLAB_TOKEN を使ってすべてのツールを提供するため、 ポートに接続できるすべてのユーザーが利用できます。そのため、GITLAB_HTTP_BEARER_TOKEN（16 文字以上。クライアントは Authorization: Bearer <token> として送信します）を設定するか、ユーザーごとのサインインを行うために --auth oauth に切り替えない限り、 ループバック以外の --host へのバインドは拒否されます。デフォルトの 127.0.0.1 へのバインドでは、どちらも必要ありません。

サーバーは python-dotenv を使って、作業ディレクトリにある .env ファイルを自動的に読み込みます。

Docker

最小構成の非 root イメージを、このリポジトリ（uv、コミット済みの uv.lock）から直接ビルドします。イメージは デフォルトで読み取り専用にロックされています（MCP_READ_ONLY=true）。書き込みを許可するには、この設定を上書きしてください。

docker build -t mcp-gitlab .

# locked read-only (the image default) — stdio for an MCP client
docker run --rm -i \
  -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
  mcp-gitlab

# allow writes: override the read-only default
docker run --rm -i \
  -e MCP_READ_ONLY=false \
  -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
  mcp-gitlab

HTTP トランスポートを使う場合は、--transport streamable-http --host 0.0.0.0 を追加してください。トークンモードでループバック以外にバインドするには、 GITLAB_HTTP_BEARER_TOKEN（16 文字以上）または GITLAB_AUTH=oauth が必要です（上記を参照）。

FAQ

mcp-gitlab は MCP 2.0 をサポートしていますか？

はい。一般に MCP 2.0 と呼ばれる MCP 2026-07-28 仕様をサポートしています。また、2025-11-25 クライアントとの互換性も維持しています。

セルフホスト版 GitLab でも動作しますか？

はい。GitLab.com とセルフホスト版 GitLab（CE および EE）で動作します。GitLab Duo や Premium は必要ありません。

どのトランスポートに対応していますか？

stdio（デフォルト）とstreamable-httpに対応しています。sseトランスポートも引き続き動作しますが、2026-07-28の仕様では非推奨となっています。OAuth 2.1 モード（--auth oauth）はstreamable-httpでのみ利用できます。

アシスタントがマージ、プッシュ、コメントできないように、mcp-gitlab を読み取り専用で実行できますか？

はい。MCP_READ_ONLY=true（またはGITLAB_READ_ONLY=true）を設定して起動してください。すると、57 個の書き込みツールと書き込みワークフローのプロンプトは一切表示されなくなるため、モデルがそれらを見ることはありません。呼び出すと「Unknown tool」が返され、プロセスの実行中に書き込みを再び有効にすることはできません。ユーザーが自分でサーバーを起動する場合は、この変数を指定せずに起動できるため、管理している起動設定（管理対象の MCP 設定、コンテナーや systemd の環境変数、ホステッドデプロイなど）で設定してください。

必要なトークンスコープは何ですか？

すべての機能を利用するには、apiスコープのトークンを使用してください。読み取り専用のデプロイでは、read_apiスコープを使用してください。サーバーは環境変数からGITLAB_TOKENを読み込みますが、書き込むことはありません。mcp-gitlab auth loginで取得したトークンは~/.config/mcp-gitlab/credentials.jsonに保存されます。

どの AI アシスタントで利用できますか？

Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot、および MCP 互換クライアントで利用できます。

mcp-gitlab をインストールするにはどうすればよいですか？

uvx mcp-gitlabを実行するか、MCP クライアントの設定に追加してください。詳しくは、上記のインストールセクションをご覧ください。

関連する MCP サーバー

• mcp-atlassian-extended — Jira + Confluence 連携（22 個のツール、15 個のリソース、5 個のプロンプト）
• mcp-coda — Coda 連携（53 個のツール、12 個のリソース、5 個のプロンプト）
• mcp-argocd — Argo CD 連携（37 個のツール、7 個のリソース、7 個のプロンプト）

開発

git clone https://github.com/vish288/mcp-gitlab.git
cd mcp-gitlab
uv sync --all-extras

uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

ライセンス

MIT