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

Related MCP server: MetaMCP Admin MCP

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
LITELLM_V1_BASE_URL=http://192.168.91.200:8888/v1
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

推荐用 双 Agent 隔离管理员与员工自助场景；权限由 LiteLLM RBAC + OpenClaw tool 白名单共同约束，MCP 本身不重复实现鉴权层。

Recommended architecture: dual agents

Feishu Bot (litellm-self)          Admin Agent (litellm-admin)
        │                                    │
        └──────── streamable-http ───────────┘
                         │
              litellm-admin-mcp :3100/mcp
                         │
                         ▼ Authorization pass-through
                   LiteLLM Proxy

MCP server connection

Add to OpenClaw MCP config (e.g. ~/.openclaw/openclaw.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"
        }
      },
      "litellm-self": {
        "url": "http://192.168.91.200:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer sk-your-self-serve-key"
        }
      }
    }
  }
}

Replace:

• url — host/port where litellm-admin-mcp runs (path must be /mcp)

• litellm-admin → LiteLLM proxy admin key (sk-*)

• litellm-self → a scoped key (self-serve or limited admin); do not reuse the root admin key for employee-facing bots

Network notes:

• OpenClaw and MCP on the same host: http://127.0.0.1:3100/mcp

• MCP in Docker, OpenClaw on host: use the host LAN IP, not container 127.0.0.1

• OpenClaw must reach both this MCP server and LiteLLM is not required — only MCP needs LITELLM_BASE_URL

Tool allowlists

Restrict tools per agent so employee bots cannot invoke destructive admin operations.

Employee self-serve (litellm-self, e.g. Feishu bot):

litellm_key_generate
litellm_key_list
litellm_key_info
litellm_user_info
litellm_model_list
litellm_model_info
litellm_usage_spend_logs
litellm_usage_user_activity

Administrator (litellm-admin): all 18 tools (see MCP Tools below).

Configure and verify:

openclaw mcp configure litellm-self \
  --include litellm_key_generate,litellm_key_list,litellm_key_info,litellm_user_info,litellm_model_list,litellm_model_info,litellm_usage_spend_logs,litellm_usage_user_activity

openclaw mcp doctor litellm-admin --probe
openclaw mcp doctor litellm-self --probe
openclaw mcp tools litellm-admin   # expect 18
openclaw mcp tools litellm-self    # expect 8 (after allowlist)

Feishu bot agent prompt (template)

Attach this system prompt to the litellm-self agent bound to your Feishu channel:

你是公司内网 LLM 服务助手。员工通过私聊可申请 API Key、查询可用模型和 token 用量。

## 申请 API Key
1. 确认员工身份（飞书 user_id / 工号）；必要时用 litellm_user_info 核对是否已有账号
2. 调用 litellm_key_generate，建议 key_alias 设为唯一标识（如 feishu:<user_id>）
3. 将返回的 onboarding.message_zh 完整发给用户，必须包含 virtual_key
4. 明确告知：API Key 仅显示一次，请勿外传，仅在内网使用

## 查模型
- litellm_model_list / litellm_model_info

## 查用量
- litellm_usage_spend_logs（按 user_id 或时间范围）
- litellm_user_info（预算、累计 spend）

## 查已有 Key
- litellm_key_list / litellm_key_info（用 key_alias）
- 注意：LiteLLM 的 key_list / key_info 不会返回完整 virtual_key，只能查元数据

## 禁止
不要创建/删除用户、删模型、全局报表等管理员操作；引导用户联系 IT/管理员。

Responsibilities: MCP vs OpenClaw

User mapping suggestion: map feishu:ou_xxx to a LiteLLM user_id on first request (litellm_user_create + litellm_key_generate), or rely on key_alias=feishu:ou_xxx if your Proxy config allows it.

Key behavior reminders

1. virtual_key is returned only once at litellm_key_generate — send onboarding.message_zh to the user immediately; afterwards use lookup_token or key_alias for management.

2. key_list / key_info never return the full key — LiteLLM limitation, not an MCP bug.

3. Set LITELLM_V1_BASE_URL on the MCP server if employees reach LiteLLM through a reverse proxy (no :8888 in the public URL); otherwise onboarding curl examples will point at the wrong host.

OpenClaw rollout checklist

# 1. MCP health (no auth)
curl -s http://192.168.91.200:3100/health

# 2. OpenClaw connectivity
openclaw mcp doctor litellm-admin --probe
openclaw mcp doctor litellm-self --probe

# 3. Tool counts
openclaw mcp tools litellm-admin
openclaw mcp tools litellm-self

MCP Tools (18)

Users (5)

Keys (5)

Models (5)

Usage (3)

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 all 18 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 (+ onboarding on generate)
    models.ts         # 5 model tools
    usage.ts          # 3 usage tools
    index.ts          # MCP server registration
  utils/
    response.ts       # ok() / fail() helpers
    onboarding.ts     # virtual key quickstart / message_zh
tests/                # Vitest unit + optional integration tests

License

See repository license file if present.