OMOS-MCP

MCP server for AI agents (Claude, ChatGPT, Cursor, etc.) to read project documents from OMOS Shared Drive and answer questions — every answer cites the source file with a Google Drive link.

Supported Drive structure:

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

Tools

Agent searches in order: filter by Project Name → if not found, check Project Overview then ask user for confirmation → continue asking about Timeline | BRD | Design (System Flow / DB / API) → if the question is too broad, it will ask back to narrow scope (embedded in server instructions).

Related MCP server: brkt-gdrive-mcp

One-Time Setup: Service Account

The server accesses Drive with a service account (no need for everyone to log in):

1. Go to console.cloud.google.com → create a new project (or use an existing one)

2. APIs & Services → Library → search for Google Drive API → click Enable

3. IAM & Admin → Service Accounts → Create Service Account → set a name like omos-mcp → click Create (skip role step, no permissions needed)

4. Go to the created service account → tab Keys → Add Key → Create new key → JSON → the key file will download

5. Copy the service account email (looks like omos-mcp@<project>.iam.gserviceaccount.com) and share the Shared Drive / OMOS folder with this email as Viewer

6. Find the folder id of the root OMOS: open the folder in a browser and look at the URL https://drive.google.com/drive/folders/<this is the id>

Environment Variables

Run Locally

Install uv first (curl -LsSf https://astral.sh/uv/install.sh | sh)

1) Set up .env (server loads it automatically from repo root):

cp .env.example .env

Edit .env to add OMOS_ROOT_FOLDER_ID and the key file path (e.g., place the key file at ./service-account.json — it's already gitignored).

2) Connect with Claude Code (stdio):

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

Claude Desktop / Cursor / Windsurf — add to MCP config:

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

3) Test: Ask the agent "What projects are in OMOS?" — you should get a list of projects with links.

(Optional) Run as an HTTP server locally: Enable OMOS_AUTH_TOKEN in .env, then

uv run omos-mcp-http

The endpoint is at http://localhost:8000/mcp; connect with:

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

Deploy as an MCP Link (Render)

1. Push this repo to GitHub (includes Dockerfile + render.yaml)

2. Render → New → Blueprint → select this repo

3. Set environment variables in the dashboard:

   • OMOS_ROOT_FOLDER_ID = folder id of the root OMOS

   • GOOGLE_SERVICE_ACCOUNT_JSON = the entire JSON key file content (paste directly)

   • OMOS_AUTH_TOKEN Render generates it automatically → copy and share with the team

4. Deployment complete → endpoint is https://<app>.onrender.com/mcp

Users connect:

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

Cursor / VS Code: Add URL + header Authorization: Bearer <token> in MCP config

Use with Claude.ai / ChatGPT (Web) — OAuth

Web clients cannot pass headers, so OAuth is required through a provider like WorkOS AuthKit (free for up to 1M users):

1. Sign up at workos.com → enable AuthKit → set login method + restrict to team members only

2. Dashboard → Connect → Configuration → enable Client ID Metadata Document and Dynamic Client Registration

3. Add Resource Indicator = https://<app>.onrender.com (without /mcp)

4. Set 3 additional env variables on Render: OAUTH_ISSUER = AuthKit domain, OAUTH_AUDIENCE = https://<app>.onrender.com, PUBLIC_URL = https://<app>.onrender.com

5. Users: Claude.ai → Settings → Connectors → Add custom connector → enter https://<app>.onrender.com/mcp → log in via WorkOS

OAuth mode and bearer token can coexist — web uses OAuth, CLI can still use the token

Test Converters

uv run python test_convert.py