OMOS-MCP

MCP-Server, der KI-Agenten (Claude, ChatGPT, Cursor usw.) das Lesen von Projektdokumenten im OMOS Shared Drive ermöglicht, um Fragen zu beantworten – jede Antwort verweist auf die Quelldatei mit einem Google Drive-Link.

Unterstützte Drive-Struktur:

OMOS/
├── Project A/
│   ├── Project Overview/
│   ├── Timeline/
│   ├── Design/
│   │   ├── System Flow/
│   │   ├── DB/
│   │   └── API/
│   └── BRD/
└── Project B/ ...

Tools

Der Agent durchsucht in dieser Reihenfolge: Filter Projektname → nicht gefunden → Projektübersicht anzeigen und beim Benutzer bestätigen lassen → weiterfragen nach Zeitplan | BRD | Design (Systemablauf / DB / API) → zu breite Fragen werden zurückgewiesen, um den Umfang einzugrenzen (in den Server-Anweisungen hinterlegt).

Related MCP server: brkt-gdrive-mcp

Einmalige Einrichtung: Service Account

Der Server greift über einen Service Account auf den Drive zu (kein Login für alle erforderlich):

1. Gehe zu console.cloud.google.com → neues Projekt erstellen (oder ein vorhandenes verwenden).

2. APIs & Services → Library → nach Google Drive API suchen → Enable klicken.

3. IAM & Admin → Service Accounts → Create Service Account → Namen vergeben, z. B. omos-mcp → Create klicken (Rollen-Schritt überspringen, keine Berechtigungen erforderlich).

4. Zum erstellten Service Account gehen → Tab Keys → Add Key → Create new key → JSON → die Schlüsseldatei wird heruntergeladen.

5. Die E-Mail des Service Accounts kopieren (sieht aus wie omos-mcp@<project>.iam.gserviceaccount.com) und den Shared Drive / OMOS-Ordner für diese E-Mail als Viewer freigeben.

6. Die Ordner-ID des OMOS-Root-Ordners finden: Ordner im Browser öffnen und die URL betrachten https://drive.google.com/drive/folders/<dies ist die id>.

Environment Variables

Lokal ausführen

Zuerst uv installieren (curl -LsSf https://astral.sh/uv/install.sh | sh).

1) .env einrichten (der Server lädt automatisch aus dem Repository-Stammverzeichnis):

cp .env.example .env

.env bearbeiten, OMOS_ROOT_FOLDER_ID und den Pfad zur Schlüsseldatei eintragen (z. B. die Schlüsseldatei unter ./service-account.json ablegen – ist bereits in .gitignore).

2) Mit Claude Code verbinden (stdio):

claude mcp add omos -- uv run --directory "/path/to/OMOS-MCP" omos-mcp

Claude Desktop / Cursor / Windsurf – in der MCP-Konfiguration eintragen:

{
  "mcpServers": {
    "omos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/OMOS-MCP", "omos-mcp"]
    }
  }
}

3) Testen: Den Agenten fragen "Welche Projekte gibt es in OMOS?" – es sollte eine Liste der Projekte mit Links erscheinen.

(Optional) Als HTTP-Server lokal ausführen: OMOS_AUTH_TOKEN in .env aktivieren, dann

uv run omos-mcp-http

Der Endpunkt ist http://localhost:8000/mcp. Verbinden mit:

claude mcp add --transport http omos http://localhost:8000/mcp -H "Authorization: Bearer <OMOS_AUTH_TOKEN>"

Als MCP-Link deployen (Render)

1. Dieses Repository auf GitHub pushen (enthält bereits Dockerfile + render.yaml).

2. Render → New → Blueprint → dieses Repository auswählen.

3. Umgebungsvariablen im Dashboard setzen:

   • OMOS_ROOT_FOLDER_ID = Ordner-ID des OMOS-Root-Ordners

   • GOOGLE_SERVICE_ACCOUNT_JSON = Inhalt der gesamten JSON-Schlüsseldatei (direkt einfügen)

   • OMOS_AUTH_TOKEN Render generiert selbst → kopieren und an das Team weitergeben

4. Nach erfolgreichem Deployment ist der Endpunkt https://<app>.onrender.com/mcp.

Benutzer verbinden sich:

claude mcp add --transport http omos https://<app>.onrender.com/mcp \
  -H "Authorization: Bearer <OMOS_AUTH_TOKEN>"

Cursor / VS Code: URL + Header Authorization: Bearer <token> in der MCP-Konfiguration eintragen.

Für Claude.ai / ChatGPT (Web) – OAuth

Web-Clients haben kein Feld für Header, daher muss OAuth über einen Anbieter wie WorkOS AuthKit (kostenlos für bis zu 1 Mio. Benutzer) verwendet werden:

1. Bei workos.com registrieren → AuthKit aktivieren → Login-Methode einrichten + auf Teammitglieder beschränken.

2. Dashboard → Connect → Configuration → Client ID Metadata Document und Dynamic Client Registration aktivieren.

3. Resource Indicator hinzufügen = https://<app>.onrender.com (ohne /mcp).

4. Auf Render 3 zusätzliche Umgebungsvariablen setzen: OAUTH_ISSUER = AuthKit-Domain, OAUTH_AUDIENCE = https://<app>.onrender.com, PUBLIC_URL = https://<app>.onrender.com.

5. Benutzer: Claude.ai → Settings → Connectors → Add custom connector → https://<app>.onrender.com/mcp eingeben → über WorkOS anmelden.

OAuth-Modus und Bearer-Token können nebeneinander existieren – Web verwendet OAuth, CLI kann weiterhin das Token verwenden.

Konverter testen

uv run python test_convert.py