セルフホストしたGiteaでgitea-mcpを使う：macOSのinstall失敗とClaude・Cursor設定

セルフホストしている Gitea を、普段使いしている Claude（Claude Code / Claude Desktop）や Cursor から MCP 経由で操作したかった。

GitHub であれば MCP 接続は非常に簡単だが、Gitea ではいくつか追加の設定が必要だった。
公式の gitea-mcp を macOS にインストールし、Gitea 側でアクセストークンを発行。その上で、両方のクライアントから同じバイナリを stdio 経由で利用するところまで試した。 VS Code など他のエディタからの接続は試していない。その場合は公式リポジトリの手順を参照してください。

macOSでmake installすると/binに書こうとして落ちる

gitea-mcp をビルドしたあと、make install を叩いたら次のエラーで止まった。

cp: /bin/gitea-mcp: Operation not permitted
make: *** [install] Error 1

最初は SIP（System Integrity Protection）に弾かれただけだと思った。sudo を付けても macOS の /bin は書き込めないので、それ自体は事実ではある。
ただ、そもそもなぜシステムディレクトリに入れようとしたのかが分からなかった。

Makefile の install ターゲットはこうなっている。

install: build
    @mkdir -p $(GOPATH)/bin
    @cp $(EXECUTABLE) $(GOPATH)/bin/$(EXECUTABLE)

$(GOPATH) は Makefile 内の make 変数で、シェルの環境変数 GOPATH を素通ししているだけだった。
ターミナルで GOPATH が未設定だと空文字列になり、$(GOPATH)/bin が /bin に化ける。
macOS の /bin は SIP で保護されたシステムボリューム上にあり、sudo を使っても書き込めないため「Operation not permitted」になる。

対処は、GOPATH を明示して make install を実行すること。

GOPATH=$(go env GOPATH) make install

あるいは事前に ~/.zshrc などで次を設定し、ターミナルを開き直してから make install する。

export GOPATH=$(go env GOPATH)
export PATH=$PATH:$GOPATH/bin

go env GOPATH が何も出さない場合は、通常 $HOME/go がデフォルトになる。

セルフホストGiteaでアクセストークンを発行する

Gitea の「アプリケーションのトークン作成」から、すべてのリポジトリを対象にしてトークンを発行した。
ホストは https://git.example.comである。(ダミーURL)

権限は「すべてのリポジトリを対象」に加えて、gitea-mcp が実際に叩く API から逆算すると次で足りた。

発行したトークンは設定ファイルに貼るので、ここでは伏せる。

ClaudeとCursorからMCP接続する

発行したトークンを使って、Claude（Claude Code / Claude Desktop）と Cursor の両方から gitea-mcp を使えるようにした。
設定はどちらも同じ JSON 形式で書ける。

{
  "mcpServers": {
    "gitea": {
      "command": "gitea-mcp",
      "args": [
        "-t", "stdio",
        "--host", "https://git.example.com",
        "--token", "<発行したトークン>"
      ]
    }
  }
}

Claude Code は claude mcp add コマンド、もしくは Claude Desktop の設定ファイルに上記を追記する。
Cursor は ~/.cursor/mcp.json（またはプロジェクト直下の .cursor/mcp.json）に同じ内容を追記すればよい。

stdio モードなので、クライアントごとにプロセスが立つだけで、同じバイナリ・同じトークンをそのまま使い回せる。
トークンは平文で設定ファイルに残るので、ファイルのパーミッションを絞るか、環境変数経由で渡す運用を検討する。

VS Code など他の MCP クライアントから繋ぐ場合は、gitea-mcp の公式リポジトリ を参照する。

まとめ

macOS で make install が /bin へ落ちるのは、未設定の GOPATH が空文字になり $(GOPATH)/bin が /bin に化けるのが原因だった。
GOPATH=$(go env GOPATH) make install するか、~/.zshrc で GOPATH と PATH を通してから入れ直す。

トークンはすべてのリポジトリを対象にし、repository / issue の読み書きと organization / user の読み取りがあれば足りる。
Claude と Cursor は同じ JSON を stdio で使い回せる。他のエディタは公式手順を見ればよい。

関連項目