gitea-mcp

gitea-mcp

Gitea 向けの Model Context Protocol サーバーです。AI アシスタント（Claude、ChatGPT、Copilot など、MCP に対応するあらゆるもの）を使って、アクセス可能な任意の Gitea インスタンス上のイシュー、リポジトリ、リリースを読み取り、作成、管理できます。

Forgejo と Codeberg（API 互換）でも動作します。

導入する理由

セルフホストの Gitea は、個人開発者、小規模チーム、プライバシーを重視する組織に人気の GitHub 代替サービスです。この MCP サーバーをインストールすると、AI アシスタントで次のことができます。

• チャットから離れることなく、監査で見つかった事項やリファクタリングのメモを Gitea のイシューとして登録する
• リポジトリのオープンイシューを自然言語でトリアージする
• コーディングセッションの最後にリリースを作成する
• 複数のリポジトリにまたがるイシューにまとめてコメントする

機能

リソース	ツール
イシュー	create_issue、list_issues、get_issue、update_issue、add_comment
リポジトリ	list_repos、list_labels、list_milestones、list_branches
プルリクエスト	list_pull_requests、get_pull_request、add_comment_on_pr、create_pr、merge_pr
ファイル	read_file、commit_changes、create_branch
リリース	list_releases、create_release
メタ情報	get_server_info、get_server_version

• パーソナルアクセストークン（PAT）によるベアラー認証
• httpx と FastMCP による非同期 HTTP
• セルフホストの Gitea、Forgejo、Codeberg で動作

クイックスタート

1. インストール

pip install gitea-mcp

または、uv を使います。

uv pip install gitea-mcp

2. パーソナルアクセストークンを生成する

Gitea インスタンスで Settings → Applications → Generate New Token に移動し、少なくとも次の権限を付与します。

• read:repository
• write:issue
• read:user

リリースも作成する場合は、write:repository を追加します。

3. MCP クライアントを設定する

Claude Desktop（対話形式）： 次を実行します。

gitea-mcp init

Gitea の URL とパーソナルアクセストークンの入力を求められ、接続が検証された後、お使いの OS に適した claude_desktop_config.json が書き込まれます（既存の設定がある場合は統合されます）。Claude Desktop を再起動すれば完了です。

いつでも次を実行して、サーバーが Gitea インスタンスに接続できるか確認できます。

gitea-mcp doctor

doctor は環境変数から GITEA_URL と GITEA_TOKEN を読み取り、GET /api/v1/user を実行して、認証済みユーザー名と MCP ツールの状態を報告します。終了コード 0 は準備完了、1 は接続または読み込みの失敗、2 は設定不足を示します。

任意の MCP クライアント（手動）： クライアントの MCP 設定に gitea-mcp を追加します。推奨形式では uvx を使用するため、クライアントは gitea-mcp を独自の PATH に追加することなく、分離された環境で公開済みの最新ホイールを起動できます（gitea-mcp init が書き込む形式です）。

{
  "mcpServers": {
    "gitea": {
      "command": "uvx",
      "args": ["gitea-mcp"],
      "env": {
        "GITEA_URL": "https://your-gitea-instance.example.com",
        "GITEA_TOKEN": "your-personal-access-token"
      }
    }
  }
}

グローバルに pip でインストールした gitea-mcp バイナリを使う場合は、args を削除し、command を直接 "gitea-mcp" に設定してください。起動時にバイナリが MCP クライアントの PATH に含まれていれば動作します。

完全な設定例は mcp.json を参照してください。同じ形式は Claude Desktop、VS Code、Cowork、Claude Code、およびその他すべての MCP 互換クライアントで使用できます。

設定

設定は環境変数から読み取られます。

変数	必須	デフォルト	説明
GITEA_URL	はい	—	Gitea インスタンスのベース URL（例：https://gitea.example.com）
GITEA_TOKEN	はい	—	Gitea のユーザー設定で発行したパーソナルアクセストークン
GITEA_TIMEOUT	いいえ	30	HTTP リクエストのタイムアウト（秒）
GITEA_MAX_RETRIES	いいえ	3	冪等メソッド（GET／PUT／DELETE）で一時的な障害が発生した場合の最大再試行回数。再試行を無効にするには 0 を設定します。POST と PATCH は自動再試行されません。イシュー、コメント、リリースが重複して作成される可能性があるためです。429 Too Many Requests はすべてのメソッドで再試行され、Retry-After が指定されている場合はその値に従います。
GITEA_RETRY_BASE_DELAY	いいえ	0.5	再試行間の指数バックオフに使う基本遅延（秒）。実際の遅延はジッターを加えて base * 2^attempt で増加し、最大 4 秒に制限されます。

セルフホスト／HTTP トランスポート

デフォルトでは、gitea-mcp は stdio モードで実行されます。各 MCP クライアント（Claude Desktop、Cowork など）が、必要に応じて独自のサブプロセスを起動します。ネットワーク経由で複数のクライアントが接続するインスタンスを 1 つセルフホストするには、ストリーマブル HTTP トランスポートを使用します。

gitea-mcp serve --transport http --host 0.0.0.0 --port 8000 --path /mcp

4 つのフラグはいずれも環境変数で指定することもできます（Docker／systemd ユニットで便利です）。

変数	デフォルト	フラグ
GITEA_MCP_TRANSPORT	stdio	--transport
GITEA_MCP_HOST	127.0.0.1	--host
GITEA_MCP_PORT	8000	--port
GITEA_MCP_PATH	/mcp	--path

MCP クライアントは、ローカルの stdio サーバーに接続する場合と同様に、生成された URL（例：https://gitea-mcp.example.com/mcp）に接続します。ただし、実行中の 1 つのインスタンスを共有します。

認証モデル（このリリース）。 サーバーは自身の環境から GITEA_TOKEN を読み取るため、URL にアクセスできるクライアントはすべて、同じ Gitea ユーザーとして動作します。ご自身で管理するアクセス制御（ファイアウォール、リバースプロキシ認証、VPN、Tailscale）の背後で実行してください。複数テナントが独自のトークンを持ち込む機能は、ロードマップに含まれています。

引数なしの起動（サブコマンドを指定しない gitea-mcp）は引き続き stdio モードで実行されるため、既存の Claude Desktop／Cowork／Claude Code との連携に影響はありません。

互換性

サーバー	状態
Gitea（セルフホスト）	✅ 主な対象
Forgejo	✅ 動作する見込み（API 互換）
Codeberg	✅ 動作する見込み（Codeberg は Forgejo を実行）

開発

git clone https://github.com/werebear73/gitea-mcp.git
cd gitea-mcp
pip install -e ".[dev]"
pre-commit install                       # commit-stage hooks (ruff + mypy)
pre-commit install --hook-type pre-push  # push-stage hooks (pytest + build check)
pytest

2 段階の pre-commit ポリシーにより、コミットのサイクルを素早く保ち（lint + type のみ）、一方で git push では、過去に CI／リリースの問題を検出した時間のかかる処理（テストスイート全体と python -m build && twine check dist/*）の完了を必須にしています。これにより、setuptools_scm のバージョンに関する想定外の問題がタグのプッシュまで進む前に検出されます。

ロードマップ

リリース済みの内容、次の予定、対象外の内容については、docs/ROADMAP.md を参照してください。

公開

• MCP Registry のメタデータは server.json で管理されています。
• Smithery と MCP Registry への公開手順は docs/PUBLISHING.md に記載されています。

バージョン管理

setuptools_scm を使用し、git タグから導出するセマンティックバージョニングです。リリース手順については VERSIONING.md を参照してください。

コントリビューション

Issue とプルリクエストを歓迎します。大規模な変更の場合は、まず Issue を作成して進め方を相談してください。

ライセンス

MIT — 商用製品を含め、自由にご利用ください。

---

Waretech Services が開発しました。