60 lines
3.4 KiB
Markdown
60 lines
3.4 KiB
Markdown
# Gitea MCP Connector
|
||
|
||
Stellt die [Forgejo/Gitea](https://git.vogt.de.com)-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](https://github.com/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*):
|
||
|
||
```json
|
||
{
|
||
"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.
|