Gitea MCPサーバーの使い方 — Claude Codeでリポジトリを操作する

Gitea MCPは、Giteaのリポジトリ・Issue・PRをClaude Codeから操作するための公式MCPサーバーgitea-mcpです。Personal Access Tokenを発行し、claude mcp addで1コマンド登録すれば使えます。Dockerイメージでも起動できます。

Giteaはセルフホストで動かすオープンソースのGitプラットフォームで、GitHubやGitLabのSaaSを使わずに自社インフラでリポジトリを管理したいチームに使われています。以下では、トークンの発行から接続、Docker導入、トークンを渡せないクライアント向けのOAuth構成までを順に説明します。

Gitea MCPサーバーとは何か

gitea-mcpは、Gitea自身が開発・公開している公式のMCPサーバーです。Go言語で書かれ、MCPプロトコルの2026-07-28版までをサポートし、クライアント側のバージョンに合わせて自動的に下位互換のプロトコルへ切り替えます。stdio(ローカル起動)とHTTP(常駐サーバー)の両方の接続方式に対応しています。

GitHub連携を扱うGitHub MCPサーバーの使い方とツールの構成は似ていますが、読者層が異なります。GitHub MCPはGitHub.com上のリポジトリが対象なのに対し、gitea-mcpは自社ホストのGiteaインスタンス(またはgitea.com)が対象です。コンプライアンス上コードを外部SaaSに置けない、あるいは既存のGitea基盤を使い続けたいチームが主な利用者になります。

Personal Access Tokenを発行する

接続にはGiteaのPersonal Access Token(PAT)が必要です。Giteaの管理画面からSettings → Applicationsに進み、トークン生成ボタンで発行します。付与するスコープは、Claudeにやらせたい操作に応じて選びます。Issueの読み書きはissueスコープ、ファイル・ブランチ・PRの操作はrepositoryスコープが基本です。Actionsのシークレットやワークフローを操作させたい場合も、repositoryスコープの書き込み権限(write:repository)が必要です。Giteaのトークンスコープにactionsという区分はありません。トークンは発行直後にしか表示されないため、その場でコピーして安全な場所に控えます。

インストール方法

インストール方法は3通りあります。最も簡単なのは公式のDockerイメージdocker.gitea.com/gitea-mcp-serverを使う方法です。バイナリを直接使いたい場合はリリースページからダウンロードしてPATHに置きます。ソースからビルドする場合はGo 1.27以上が必要です。

git clone https://gitea.com/gitea/gitea-mcp.git
cd gitea-mcp
make install

Dockerで起動する

Dockerで動かす場合の基本形は次のdocker runです。stdioで使うため-iを付け、トークンは-eで渡します。

docker run -i --rm \
  -e GITEA_ACCESS_TOKEN=your_pat_here \
  -e GITEA_HOST=https://gitea.example.com \
  docker.gitea.com/gitea-mcp-server

Claude Codeに登録するときは、このdocker runを次節のclaude mcp addの--以降に置きます。

Claude Codeへの接続手順

Claude Codeででは、stdioサーバーとして登録します。以下の2通りの登録方法を用意しました。

claude mcp add --transport stdio --scope user gitea \
  --env GITEA_ACCESS_TOKEN=your_pat_here \
  --env GITEA_HOST=https://gitea.com \
  -- go run gitea.com/gitea/gitea-mcp@latest -t stdio

1つ目の例のGITEA_HOSTは自社インスタンスのURLに置き換えます。2つ目はDockerイメージ経由の登録です。

claude mcp add --transport stdio --scope user gitea \
  --env GITEA_ACCESS_TOKEN=your_pat_here \
  --env GITEA_HOST=https://gitea.example.com \
  -- docker run -i --rm -e GITEA_ACCESS_TOKEN -e GITEA_HOST docker.gitea.com/gitea-mcp-server

claude mcp addは設定を書き込むだけで、トークンの正しさは検証しません(Claude Code公式ドキュメントの記述)。--scope projectを付けると、作業ディレクトリの.mcp.jsonにサーバー定義が作られます。接続の成否はclaude mcp listの✔ Connectedか✘ Failed to connectで見ます。

バイナリ版を直接使う場合は、gitea-mcp -t stdio -H <host> -T <token>の形式でホストとトークンをフラグ渡しできます。フラグと環境変数はフラグが優先されるため、CI環境など値を都度切り替えたい場面ではフラグ指定が扱いやすくなります。MCPサーバー登録の一般的な作法はMCPとは — AIと外部ツールをつなぐ標準プロトコルにまとめています。

HTTPモードで常駐させる場合はgitea-mcp -t http --port 8080で起動し、クライアント側はurlとAuthorizationヘッダーで接続します。ヘッダーの値はBearer <token>とtoken <token>のどちらの形式も受け付けます。これはリクエストごとにGiteaの資格情報をそのまま渡すクレデンシャルパススルーで、MCP標準のOAuthフローではありません。トークンの管理はクライアント側に残ります。

HTTPは常にステートレスで、/mcpエンドポイントはPOSTのみを受け付け、セッションIDやSSEの再開機能は持ちません。リバースプロキシを挟む場合はMcp-Protocol-Version・Mcp-Method・Mcp-Nameヘッダーをそのまま転送する必要があります。OAuthモードでは、/mcpが受け付けるホストは-oauth-public-urlのホストかループバックだけなので、Hostヘッダーも書き換えずに転送します。

トークンを渡せないクライアントはOAuthで接続する

PATを直接渡せない場合は、gitea-mcpをOAuth 2.1モードで起動する構成があります。READMEは対象として、Web・モバイル版のClaude.aiを挙げています。OAuthモードでも-rを付けると、要求するスコープが読み取り専用に絞られます。利用者は共有トークンではなく、各自のGiteaアカウントの権限で動きます。

gitea-mcp -t http -oauth -oauth-public-url https://mcp.example.com -H https://gitea.example.com

Claude Code側は、事前登録したクライアントIDとコールバックポートをclaude mcp addで渡せます。次の設定はv2.1.285で--scope projectを付けて実行し、.mcp.jsonに書き出された内容です(接続は行っていません)。

claude mcp add --transport http --scope project \
  --client-id my-client-id --callback-port 8080 \
  gitea https://mcp.example.com/mcp

{
  "mcpServers": {
    "gitea": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": { "clientId": "my-client-id", "callbackPort": 8080 }
    }
  }
}

注意点が1つあります。Claude Codeの公式ドキュメントは、コールバックURIがv2.1.231以降http://localhost:PORT/callbackの形だと説明しています。READMEが挙げるのは127.0.0.1の形です。Claude Code公式ドキュメントはv2.1.229の不一致への回避策として、サーバー側に127.0.0.1形のURIを追加登録する方法を示しています。今回の組み合わせなら、Giteaにhttp://localhost:<ポート>/callbackも併せて登録しておく手があります。この構成での効果は未検証で、失敗した場合はGiteaに登録したURIと実際の要求を見比べます。

使えるツール一覧とスコープ制御

ツールは50種類を超え、いずれもScope(機能領域)とAccess(Read/Write)で分類されています。主なスコープは次のとおりです。

表に挙げたスコープ以外にもlabel・milestone・branch・tag・commit・searchのほか、packages・project・user・versionがあります。issue_writeやpull_request_writeは、1つのツールがmethodパラメータで複数の操作を切り替える設計です。

書き込み系ツールは-r(またはGITEA_READONLY環境変数)を付けると起動時に非表示にでき、読み取り専用運用が可能です。特定のスコープだけを読み込みたい場合は-S(GITEA_SCOPES)でスコープ名を絞り、個別ツール名で絞りたい場合は-O(GITEA_TOOLS)を使います。両方を同時に指定すると、選んだスコープと個別ツールの和集合が読み込まれます。

gitea-mcp -r -S issue,pull_request

このコマンドはIssueとPull Requestのスコープだけを読み取り専用で公開します。共有プロジェクトでClaudeに触らせる範囲を絞りたいときに使う設定です。

実際の使い方

接続直後に「Gitea MCPサーバーのバージョンを教えて」と聞くとget_gitea_mcp_server_versionが呼ばれます。認証まで通っているかを見たいときは、認証中のユーザーを返すget_meが向きます。READMEが案内する最初の動作確認は「list all my repositories」です。

接続が済んだら「自分のリポジトリを一覧して」と頼むだけでlist_my_reposが呼ばれ、所有リポジトリの一覧が返ります。「このリポジトリの未対応Issueを教えて」と聞けばlist_issuesが動き、「このPRの差分をレビューして」と頼めばpull_request_readがdiffとレビューコメントを取得してClaudeに読ませます。

Actionsのログを追わせることもできます。「直近のワークフロー実行が失敗した理由を教えて」と聞くとactions_run_readがジョブとログを取得し、失敗箇所の特定まで一気に進みます。ページングが必要な一覧系ツールはpageとper_pageパラメータを受け付けますが、実際の上限はGiteaサーバー側の[api].MAX_RESPONSE_ITEMS設定(既定50件)で頭打ちになり、それより大きい値を指定しても黙って切り詰められます。

コードレビューの補助にも使えます。「このPRの変更点を要約して、レビューコメントを付けて」と頼めばpull_request_readでdiffとファイル一覧を取得したうえでpull_request_review_writeがレビューコメントを投稿します。リリース作業では「v1.2.0のリリースノートを前回リリースからの差分で作成して」と頼めば、list_commitsやlist_tagsで履歴を拾い、create_releaseで作成します。Wikiならwiki_writeで更新できます。

よくあるつまずき

• Dockerのヘルスチェック: HTTPモードは/healthzを提供し、KubernetesのhttpGetプローブに使えます。Dockerイメージの組み込みヘルスチェックは、stdioとHTTPの両モードで動きます。読み取り専用のルートファイルシステムで動かすときは、/tmpにtmpfsをマウントします
• ページングの上限はサーバー設定次第: per_pageを100や200に指定してもGitea側のMAX_RESPONSE_ITEMS(既定50)を超えた分は返ってきません。大量データを扱う場合はページを分けて取得します
• ログの場所: gitea-mcpのログは$HOME/.gitea-mcp/gitea-mcp.logに書かれ、-dでデバッグログになります。Unixソケットで待ち受けるGiteaには-gitea-unix-socket <path>で届き、ホストの既定値はhttp://unix/です
• 予約名との衝突: workspaceやclaude-in-chromeなど、ビルトインサーバーの名前は予約されており、claude mcp addは予約名をエラーで拒否します。giteaのような名前なら衝突しません
• スコープ不足による書き込み失敗: PATに必要なスコープが無いと、Gitea APIが権限エラーを返し、ツールの結果がエラーになります。「Issueにコメントできない」といった症状が出たら、まずトークンのスコープ設定を見直します

まとめ

ローカルのClaude Codeだけで使うなら、PATとstdioの登録で足ります。Claude.aiのWeb・モバイルからも使うなら、OAuthアプリの登録とHTTPS公開が別途必要になります。