litellm-admin-mcp

litellm-admin-mcp

LiteLLM Admin MCP server for OpenClaw. Exposes LiteLLM Proxy admin APIs (internal users, virtual keys, spend logs) as MCP tools over streamable-http, so agents can manage LiteLLM without custom HTTP glue.

将 LiteLLM Proxy 的管理能力封装为 MCP Server，供 OpenClaw Agent 通过 streamable-http 调用。

Overview

OpenClaw Agent ──streamable-http + Bearer sk-*──► litellm-admin-mcp :3100/mcp
                                                        │
                                                        ▼ Authorization pass-through
                                                  LiteLLM Proxy

Prerequisites

• Node.js 20+ (engines.node in package.json)
• A running LiteLLM Proxy with a valid admin key (sk-*)
• For OpenClaw integration: OpenClaw CLI with MCP support

Install & Run

# Install dependencies
npm install

# Development (hot reload)
npm run dev

# Production build
npm run build
npm start

Default listen address: http://0.0.0.0:3100

• Health: http://localhost:3100/health
• MCP: http://localhost:3100/mcp

Docker Deployment

Quick start (docker compose)

docker compose up -d --build
docker compose logs -f litellm-admin-mcp
curl -s http://localhost:3100/health

Optional .env beside docker-compose.yml:

LITELLM_BASE_URL=http://192.168.91.200:8888
PORT=3100

Network note: The container must reach LiteLLM at LITELLM_BASE_URL. From inside Docker, 127.0.0.1 points to the container itself — use the host LAN IP or host.docker.internal (Docker Desktop).

Build and run manually

docker build -t litellm-admin-mcp:latest .

docker run -d \
  --name litellm-admin-mcp \
  -p 3100:3100 \
  -e LITELLM_BASE_URL=http://192.168.91.200:8888 \
  --restart unless-stopped \
  litellm-admin-mcp:latest

Stop: docker compose down or docker stop litellm-admin-mcp && docker rm litellm-admin-mcp

Environment Variables

Copy .env.example and adjust as needed:

cp .env.example .env

Example:

export LITELLM_BASE_URL=http://your-litellm-host:8888
export PORT=3100
export HOST=0.0.0.0
npm run dev

Admin key is not an environment variable. Configure it in the MCP client (e.g. OpenClaw headers), not in this server's env.

Authentication

Every request to /mcp must include:

Authorization: Bearer sk-<your-litellm-admin-key>

Behavior:

1. Missing or invalid header (must start with Bearer sk-) → 401 from this server; LiteLLM is not called.
2. Valid header → forwarded unchanged to LiteLLM API calls made by tool handlers.

OpenClaw (or any MCP client) supplies the key per session. Rotate keys in the client config without redeploying this server.

OpenClaw Configuration

Add to your OpenClaw MCP config (e.g. ~/.openclaw/config.json or project-level MCP settings):

{
  "mcp": {
    "servers": {
      "litellm-admin": {
        "url": "http://192.168.91.200:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer sk-your-admin-key"
        }
      }
    }
  }
}

Replace:

• url — host/port where litellm-admin-mcp runs (path must be /mcp)
• Authorization — your LiteLLM admin key (sk-*)

If OpenClaw and this server run on the same machine, http://127.0.0.1:3100/mcp works. For remote hosts, use the reachable IP/hostname and ensure firewall access to PORT.

MCP Tools (11)

Tool responses use a unified envelope:

{ "success": true, "data": {} }

{ "success": false, "error": { "status": 400, "message": "...", "detail": {} } }

Verification

Health check (no auth)

curl -s http://localhost:3100/health
# {"status":"ok"}

OpenClaw MCP probe

With the server running and OpenClaw configured:

openclaw mcp doctor --probe

Confirm litellm-admin (or your server alias) reports a healthy streamable-http connection and lists the 11 tools.

Testing

# Unit tests (default, no live LiteLLM)
npm test

# Optional integration tests against a real LiteLLM instance
RUN_INTEGRATION=1 npm test

# With custom LiteLLM URL / admin key for integration
LITELLM_BASE_URL=http://your-host:8888 LITELLM_ADMIN_KEY=sk-your-key RUN_INTEGRATION=1 npm test

Integration tests are read-only (user/list, key/list). They are skipped unless RUN_INTEGRATION=1.

Security

Treat the LiteLLM admin key (sk-*) as a root credential.

• It can create/delete users and keys, change budgets, and read spend data.
• Store it only in trusted MCP client config (OpenClaw headers), secret managers, or CI secrets — never commit it to git.
• This server does not add a second auth layer; anyone who can reach /mcp with a valid admin key can perform admin actions on your LiteLLM Proxy.
• Bind to 127.0.0.1 or place the service behind a private network / reverse proxy with TLS if exposed beyond localhost.
• Do not log full sk-* values. key_generate may return a new plaintext key once (LiteLLM behavior); handle that response carefully.

Project Layout

Dockerfile            # Multi-stage production image
docker-compose.yml    # One-command deployment
src/
  server.ts           # Hono app, /health, /mcp transport
  litellm-client.ts   # LiteLLM HTTP client with auth pass-through
  tools/
    users.ts          # 5 user tools
    keys.ts           # 5 key tools
    usage.ts          # 1 usage tool
    index.ts          # MCP server registration
  utils/response.ts   # ok() / fail() helpers
tests/                # Vitest unit + optional integration tests

License

See repository license file if present.