Gitea MCPサーバーの使い方 — Claude Codeでリポジトリを操作する
セルフホストGitのGiteaを公式MCPサーバーでClaude Codeにつなぐ手順です。Personal Access Token認証、Docker導入、Issue・PR・Actionsの操作までを扱います。
Giteaはセルフホストで動かすオープンソースのGitプラットフォームで、GitHubやGitLabのSaaSを使わずに自社インフラでリポジトリを管理したいチームに使われています。公式MCPサーバーgitea-mcpを使えば、そのGiteaインスタンスに対してClaude Codeからリポジトリ・Issue・PR・Actionsを自然文で操作できます。この記事ではPersonal Access Tokenの発行からClaude Codeへの接続、Docker導入までの手順をまとめます。
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に進み、Generate New Tokenでトークンを発行します。付与するスコープは、Claudeにやらせたい操作に応じて選びます。Issueの読み書きだけならissue関連のスコープで十分ですが、Actionsのシークレットを操作させたい場合は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 installClaude Codeへの接続手順
Claude Codeではgo run経由でstdioサーバーとして登録する方法が公式READMEに明記されています。Goがインストールされていれば、事前ビルドなしでそのまま実行できます。
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 stdioGITEA_HOSTは自社インスタンスのURLに置き換えます。Goを入れずに済ませたい場合は、公式Dockerイメージ経由で同じ環境変数をそのまま渡してstdio登録できます。
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-serverGITEA_HOSTをDocker版で省略すると接続先が意図と異なるホストになるため、go run版と同様に自社インスタンスのURLを指定します。登録後はclaude mcp listを実行し、✔ Connectedと表示されることを確認します。
バイナリ版を直接使う場合は、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>のどちらの形式も受け付けますが、これはMCP標準のOAuthフローではなく、リクエストごとにGiteaの資格情報をそのまま渡すクレデンシャルパススルーという位置づけです。OAuthのような認可サーバーとのやり取りは発生しないため、トークンの管理責任はクライアント側に残ります。
HTTPは常にステートレスで、/mcpエンドポイントはPOSTのみを受け付け、セッションIDやSSEの再開機能は持ちません。リバースプロキシを挟む場合はMcp-Protocol-Version・Mcp-Method・Mcp-Nameヘッダーをそのまま転送する必要があります。転送を落とすリバースプロキシ設定のままだと、クライアントとサーバーのプロトコルバージョンがすれ違い、接続はできてもツール一覧が正しく返らないといった不具合につながります。
使えるツール一覧とスコープ制御
ツールは約50種類あり、いずれもScope(機能領域)とAccess(Read/Write)で分類されています。主なスコープは次のとおりです。
| スコープ | 代表ツール | できること |
|---|---|---|
repository | 代表ツールcreate_repo / fork_repo / list_my_repos | できることリポジトリの作成・フォーク・一覧取得 |
issue | 代表ツールissue_read / issue_write | できることIssueの参照・作成・コメント・ラベル管理 |
pull_request | 代表ツールpull_request_read / pull_request_write | できることPRの参照・作成・マージ・レビュー管理 |
actions | 代表ツールactions_run_read / actions_config_write | できることActionsのワークフロー参照・シークレット管理 |
file | 代表ツールget_file_contents / create_or_update_file | できることファイルの参照・作成・更新・削除 |
wiki | 代表ツールwiki_read / wiki_write | できることWikiページの参照・編集 |
release | 代表ツールcreate_release / list_releases | できることリリースの作成・一覧取得 |
notification | 代表ツールnotification_read / notification_write | できること通知の一覧取得・既読化 |
timetracking | 代表ツールtimetracking_read / timetracking_write | できること工数記録の参照・ストップウォッチ操作 |
表に挙げたスコープ以外にもlabel(ラベル管理)・milestone(マイルストーン管理)・branch(ブランチ操作)・tag(タグ操作)・commit(コミット参照)・search(横断検索)といったスコープがあり、合計すると50を超えるツールが公開されます。ツール名を見るとissue_writeやpull_request_writeのように1つの名前で複数操作をまとめているものがありますが、これは意図的な設計です。作成・更新・削除のような関連操作を1ツールに集約し、内部のmethodパラメータで「create」「update」「delete」を切り替える形にすることで、クライアント側に提示されるツール数を抑えています。
書き込み系ツールは-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が呼ばれ、正しく繋がっているかをすぐに確認できます。README自体もこの動作確認を最初のステップとして案内しています。
接続が済んだら「自分のリポジトリを一覧して」と頼むだけでlist_my_reposが呼ばれ、所有リポジトリの一覧が返ります。「このリポジトリの未対応Issueを教えて」と聞けばlist_repo_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で管理しているプロジェクトなら、「READMEの内容をもとにWikiのセットアップページを更新して」のように頼んでwiki_writeで反映させることもできます。いずれも「対象のリポジトリを指定して自然文で頼む」という同じ流れで完結し、GitHub MCPサーバーを使ったことがあれば操作感はほぼ共通しています。
よくあるつまずき
- HTTPモードでの
/healthzはstdio運用では使えない: DockerイメージのHEALTHCHECKはデフォルトで/healthzを叩きますが、stdioモードではこのエンドポイントを提供しません。stdioで動かす場合はヘルスチェック設定を無効化するか上書きします - ページングの上限はサーバー設定次第:
per_pageを100や200に指定してもGitea側のMAX_RESPONSE_ITEMS(既定50)を超えた分は返ってきません。大量データを扱う場合はページを分けて取得します - 予約名との衝突: Claude Codeは
workspaceのようないくつかの名前をビルトインサーバー用に予約しています。サーバー登録名はgiteaのように予約語と被らない名前にします - スコープ不足による書き込み失敗: PATに必要なスコープが無いと、書き込み系ツールは接続自体はできても実行時にエラーを返します。「Issueにコメントできない」といった症状が出たら、まずトークンのスコープ設定を見直します
まとめ
自社ホストのGiteaでコードを管理しているチームであれば、gitea-mcpはGitHub MCPサーバーの自社版として素直に使えます。読み取り専用フラグとスコープ絞り込みの両方が用意されているため、まずはissueとpull_requestスコープの読み取り専用から試し、必要に応じて書き込み権限を広げていくのが安全な導入手順です。トークンのスコープとMCPサーバー側のスコープ絞り込みという二重のゲートを両方使えば、大きな権限のPATしか発行できない環境でも実際にClaudeへ渡す操作範囲は最小限に保てます。