Docker-Container/Gitea MCP Connector

Gitea MCP Connector

Stellt die Forgejo/Gitea-API als MCP-Server (Model Context Protocol) bereit, damit Claude (Claude Desktop) lesend und schreibend auf Repositories, Dateien, Issues, Pull Requests etc. zugreifen kann.

Basiert auf dem Open-Source-Projekt Sqcows/forgejo-mcp (npm-Paket @ric_/forgejo-mcp).

Architektur (aktuell: stdio, lokal)

Claude Desktop
        │  STDIO (lokaler Prozess, kein Netzwerk-Exposure)
        ▼
npx @ric_/forgejo-mcp
        │  REST-API + FORGEJO_TOKEN
        ▼
Gitea/Forgejo-Instanz (git.vogt.de.com)

Wichtig: Dieses Setup läuft rein lokal auf dem jeweiligen Client-Rechner über die npx-STDIO-Anbindung von Claude Desktop – es gibt keinen extern erreichbaren HTTP-Endpunkt, keinen Reverse Proxy und keinen X-Api-Key-Schutz mehr nötig, weil nichts öffentlich exponiert wird.

Frühere Version dieses Dokuments beschrieb ein Docker/Pangolin-basiertes Remote-Setup (gitea-mcp.vogt.de.com, HTTP-Transport, X-Api-Key-Header). Dieses Setup wurde stillgelegt, da für den aktuellen Anwendungsfall (nur lokaler Zugriff von einem Gerät) unnötig komplex und fehleranfällig (Session-Konflikte bei mehrfachen mcp-remote-Neustarts). Falls in Zukunft wieder Remote-/Multi-Geräte-Zugriff benötigt wird, kann der Docker-Weg reaktiviert werden – Details siehe Git-Historie dieser Datei.

Claude Desktop Konfiguration

In claude_desktop_config.json (Menü Konnektoren → Lokale MCP-Server → Config bearbeiten):

{
  "mcpServers": {
    "gitea": {
      "command": "npx",
      "args": ["@ric_/forgejo-mcp"],
      "env": {
        "FORGEJO_URL": "https://git.vogt.de.com",
        "FORGEJO_TOKEN": "<Gitea/Forgejo Personal Access Token>"
      }
    }
  }
}

FORGEJO_TOKEN: Personal Access Token aus Gitea, erstellt unter Einstellungen → Anwendungen → Zugriffstoken erzeugen, mit Scopes read:repository + write:repository (idealerweise von einem dedizierten Service-User statt des Haupt-Accounts).

Danach Claude Desktop komplett beenden (nicht nur das Fenster schließen) und neu starten. Die Gitea-Tools stehen dann automatisch in jedem neuen Chat zur Verfügung, ohne pro Chat neu verbunden werden zu müssen.

Verfügbare Tools

Je nach Token-Gültigkeit/-Scope zeigt der Server unterschiedlich viele Tools:

• Ohne gültigen Token / nur Lesezugriff: nur öffentlich zugängliche Endpunkte – search_repos, search_users, get_nodeinfo, get_server_version
• Mit gültigem Token inkl. Schreibrechten: zusätzlich u. a. create_file, update_file, get_file_contents, delete_file sowie Issue-, PR- und weitere Repo-Management-Tools

Falls nach dem Einrichten nur die vier Lese-Tools erscheinen, ist das ein starkes Indiz für einen ungültigen/fehlenden FORGEJO_TOKEN – Wert in der Config prüfen (kein Platzhalter wie ${FORGEJO_TOKEN}, sondern der tatsächliche Token-String) und Claude Desktop neu starten.

Sicherheitshinweise

• Der Token liegt im Klartext in claude_desktop_config.json auf dem jeweiligen Client-Rechner. Zugriff auf diese Datei entspricht Zugriff auf das Gitea-Konto im Umfang des Token-Scopes.
• Empfohlen: dedizierter Gitea-Service-User mit möglichst eng gefasstem Token-Scope statt eines Admin-Tokens.
• Tokens, die versehentlich in Chat-Verläufen, Logs oder Screenshots sichtbar wurden, sollten zeitnah in Gitea rotiert werden.