github-org-mcp

A stateless HTTP MCP service that exposes GitHub organization member management (list / view / add / update role / remove members, and manage invitations) as Model Context Protocol (MCP) tools consumable by Claude and other MCP clients.

The OAuth flow is handled upstream — this service does not perform OAuth. The caller passes a GitHub OAuth access token and the org slug on each request via HTTP headers; the service maps the token to Authorization: Bearer <token> when calling the GitHub REST API.

Architecture

• Stateless — no user state, no credential storage, no session data persisted between requests.

• Concurrent-safe — per-request credential isolation via Python contextvars; concurrent requests never bleed token/org.

• Dual auth modes — per-request credentials via HTTP headers (gateway mode, default, SOP-compliant) or single shared credentials (env mode, local dev only).

• Two transports — HTTP server (MCP_TRANSPORT=http) for production, stdio (MCP_TRANSPORT=stdio) for local development.

Endpoints

Default port: 8080 (configurable via MCP_HTTP_PORT).

Authentication — HEADER Parameters

In gateway mode (default), every POST /mcp request must carry both headers below. Requests missing either header receive 401. Credentials are never stored globally or persisted; each request's token and org live only in a contextvars.ContextVar and are reset when the request completes.

The header names are configurable via GITHUB_TOKEN_HEADER / GITHUB_ORG_HEADER.

Service Parameters

Auth Modes

gateway mode (default, production, SOP-compliant):

• Each request must include the X-GitHub-Token and X-GitHub-Org headers.

• No credentials are stored globally — isolated per request via Python contextvars.

• Returns 401 if either header is missing.

env mode (local dev only — not SOP-compliant for production):

• Set AUTH_MODE=env, GITHUB_TOKEN, and GITHUB_ORG in the environment or .env.

• All requests share the same credentials loaded at startup — violates per-request credential isolation.

• Do not use in production or multi-tenant deployments.

Tool List

All tools follow the naming convention github_<action>_<resource> and operate on the org resolved from the request context (X-GitHub-Org).

The token's OAuth scopes / org permissions determine which operations succeed. Write operations (set/remove/create/cancel) require the token to belong to an org owner or an app with the appropriate org-members permission.

Quick Start

Local development (stdio)

cp .env.example .env
# Edit .env: set GITHUB_TOKEN, GITHUB_ORG, AUTH_MODE=env, MCP_TRANSPORT=stdio
uv sync
python -m github_org_mcp

HTTP server (gateway mode — default, SOP-compliant)

MCP_TRANSPORT=http python -m github_org_mcp
# Pass credentials per-request via X-GitHub-Token and X-GitHub-Org headers

Docker

docker compose up --build

Test Examples

Health check

curl http://localhost:8080/health

Expected response:

{"status": "ok", "transport": "http", "auth_mode": "gateway"}

Missing headers → 401 (gateway mode)

curl -i -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# → HTTP/1.1 401, body includes "required_headers": ["X-GitHub-Token", "X-GitHub-Org"]

List MCP tools

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-GitHub-Token: your_oauth_access_token" \
  -H "X-GitHub-Org: my-company" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Call a tool — list org members

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-GitHub-Token: your_oauth_access_token" \
  -H "X-GitHub-Org: my-company" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "github_list_org_members",
      "arguments": {"role": "all", "per_page": 30, "page": 1}
    }
  }'

Call a tool — invite a user by email

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-GitHub-Token: your_oauth_access_token" \
  -H "X-GitHub-Org: my-company" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "github_create_org_invitation",
      "arguments": {"email": "newhire@example.com", "role": "direct_member"}
    }
  }'

Security

• Credentials are never stored globally or persisted between requests.

• Each request's token and org are isolated in contextvars.ContextVar and reset after the request completes.

• The service runs as a non-root user (github, uid 1001) inside the container.

• Never commit real tokens or org secrets — .gitignore excludes .env.