mcp-apisix

Apache APISIX Admin API MCP Server —— 让 AI 助手查询与管理 APISIX 网关配置。

兼容 APISIX 2.x/3.x，响应格式（v2/v3）自动探测（优先依据 X-API-VERSION 响应头，头缺失时按响应体结构推断）。

特性

• 多协议传输：stdio（默认）、sse、streamable-http
• HTTP 接口认证：Bearer Token 保护，未授权请求返回 401
• 写前确认：创建 / 更新 / 切换状态等写操作触发 MCP 2.0 Elicitation 确认
• MCP Resources：apisix:// URI 暴露服务器环境等只读元数据
• Stateless HTTP：无会话状态，适配 Serverless / 多副本部署
• 凭据脱敏：强制启用（不可关闭），消费者凭据、插件密钥等响应时自动遮盖
• 默认只读：写工具默认不注册，需显式 APISIX_READ_ONLY=false 开启
• 灵活部署：uvx 免安装、Docker 公开镜像、或本地构建

快速开始

MCP 客户端（stdio，本地）

Claude Code 示例，写入项目 .mcp.json 或全局 ~/.claude.json：

{
  "mcpServers": {
    "apisix": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-apisix"],
      "env": {
        "APISIX_BASE_URL": "http://localhost:9180",
        "APISIX_ADMIN_KEY": "your-admin-key",
        "APISIX_READ_ONLY": "false"
      }
    }
  }
}

Cursor / OpenCode / Claude Desktop 等客户端格式相同：command: uvx + args: ["mcp-apisix"] + APISIX_* 环境变量。

APISIX_BASE_URL 格式：scheme://host[:port]。Admin API 默认独立监听 9180，Data Plane 监听 9080，二者分离。典型取值：

部署形态	APISIX_BASE_URL 示例
默认	http://<host>:9180
经反向代理转发	填代理对外完整地址
自签名 TLS	https://<host>:9180 + APISIX_INSECURE=true

Docker（公开镜像，免构建）

公开镜像：ghcr.io/zhouweico/mcp-apisix:latest。

方式一：stdio（客户端拉起容器）

{
  "mcpServers": {
    "apisix": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/zhouweico/mcp-apisix:latest"],
      "env": {
        "APISIX_BASE_URL": "http://your-apisix-host:9180",
        "APISIX_ADMIN_KEY": "your-admin-key",
        "APISIX_READ_ONLY": "false"
      }
    }
  }
}

必须带 -i（保持 stdin 管道）。

方式二：HTTP + 认证（容器独立运行）

容器启动时会校验 APISIX_ADMIN_KEY（缺失则 ${VAR:?...} 报错退出），必须显式传入。

启动容器：

docker run -d -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_AUTH_TOKEN=your-strong-token \
  -e APISIX_BASE_URL=http://your-apisix-host:9180 \
  -e APISIX_ADMIN_KEY=your-admin-key \
  -e APISIX_READ_ONLY=false \
  ghcr.io/zhouweico/mcp-apisix:latest

客户端 .mcp.json：

{
  "mcpServers": {
    "apisix": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-strong-token"
      }
    }
  }
}

可用工具

共 22 个原子工具 + 1 个 MCP Resource。

资源读取（11 个，只读）

所有 list_* 工具共享通用参数：page / page_size（有效区间 [10, 500]）/ detail（返回完整配置）/ fields（JSON 数组，覆盖默认投影；detail=true 时忽略）。所有资源响应统一经过脱敏层。

工具	对应端点	资源特有过滤参数	只读模式
apisix_list_routes	GET /routes	name / uri / label（v3）/ service_id / upstream_id（引用过滤，≥3.13）	✅
apisix_get_route	GET /routes/{id}	—	✅
apisix_list_services	GET /services	无	✅
apisix_get_service	GET /services/{id}	—	✅
apisix_list_upstreams	GET /upstreams	无	✅
apisix_get_upstream	GET /upstreams/{id}	—	✅
apisix_list_consumers	GET /consumers	无（凭据字段已脱敏）	✅
apisix_get_consumer	GET /consumers/{username}	—（凭据字段已脱敏）	✅
apisix_list_global_rules	GET /global_rules	无	✅
apisix_list_stream_routes	GET /stream_routes	无	✅
apisix_list_plugin_configs	GET /plugin_configs	无	✅

global_rules / stream_routes / plugin_configs 有意只提供 list，不提供 get：资源数量通常很少，一次 list 即可获取全部。需完整配置时传 detail=true。

语义支撑（3 个，只读）

工具	对应端点	说明	只读模式
apisix_list_plugins	GET /plugins/list	插件名数组（按 priority 降序，不含 schema）；subsystem 取 http（默认）或 stream	✅
apisix_get_plugin_schema	GET /schema/plugins/{name}	单个插件字段定义、类型、必填项、默认值（含 metadata_schema 与 consumer_schema）	✅
apisix_get_server_info	探测层数据	响应格式（v2/v3）与可用能力清单，告知 AI 当前环境的能力边界	✅

资源配置校验（1 个，只读）

工具	对应端点	说明	只读模式
apisix_validate_resource_config	POST /schema/validate/{resource}（≥3.5）	校验配置是否符合 JSON schema；仅校验 schema，不校验引用存在性与插件合法性；通过不代表写入必定成功	✅

写操作（7 个，APISIX_READ_ONLY=true 时不注册）

工具	语义	只读模式
apisix_create_route	POST 创建（服务端生成 id）	❌
apisix_update_route	PATCH 增量（带乐观锁）	❌
apisix_toggle_route	PATCH status 0/1（仅 route 有此字段）	❌
apisix_create_upstream	POST 创建（服务端生成 id）	❌
apisix_update_upstream	PATCH 增量	❌
apisix_create_service	POST 创建（服务端生成 id）	❌
apisix_update_service	PATCH 增量	❌

写操作约定：

• create 严格用 POST，服务端生成 id，不接受 id 参数；禁止 PUT（会静默全量覆盖且无乐观锁）
• update 用 PATCH，仅传需修改字段，未提及字段保持不变；自带乐观锁，配置在读取后被其他来源修改会返回冲突提示
• toggle 仅限 route：upstream 和 service 的 schema 无 status 字段，不提供 toggle
• 不提供 DELETE：破坏性过大，需删除时通过 APISIX Dashboard 或 Admin API 手动处理
• 不提供 consumer 写操作：consumer 涉及凭据写入，风险过高

写前确认：所有写工具执行前通过 ctx.elicit() 向用户确认；stdio 等不支持 Elicitation 的客户端降级直接执行，返回结果中标注"未经人工确认"。

多来源共管风险：APISIX 配置可能同时被 Dashboard、Ingress Controller（源自 ApisixRoute 等 CRD）等多方管理。若目标资源由声明式控制器管理，此处修改可能在数秒后被控制器按 CRD 覆盖回原状。写工具的返回结果中会显式提示此风险。

APISIX 概念

• route：核心路由配置，匹配请求并指向 upstream 或 service
• service：可复用的服务配置（upstream + plugins），被 route 引用
• upstream：后端节点集合（含负载均衡策略、健康检查等）
• consumer：消费者身份，承载认证凭据（如 key-auth 的 key）与限流配额
• global_rules：全局生效的插件配置，作用于所有路由
• plugin_configs：可复用的插件配置组，被 route 引用
• stream_routes：四层（TCP/UDP）流路由

响应格式 v2/v3：APISIX 3.x 可通过 deployment.admin.admin_api_version 配置返回 v2 格式，APISIX 2.x 原生返回 v2 格式。本 Server 自动探测响应格式（优先依据 X-API-VERSION 响应头，头缺失时按响应体结构推断），无需手动配置。v2 格式下分页与过滤参数被服务端静默忽略，返回结果中会显式告知。

配置

环境变量

MCP 传输与认证

变量	说明	默认值
MCP_TRANSPORT	传输协议：stdio / sse / streamable-http	stdio
MCP_HOST	HTTP 监听地址（stdio 忽略）	0.0.0.0
MCP_PORT	HTTP 监听端口（stdio 忽略）	8000
MCP_AUTH_TOKEN	非空时启用 Bearer Token 认证	-（不鉴权）
MCP_STATELESS_HTTP	启用无状态 HTTP（适配 Serverless）	false
MCP_LOG_LEVEL	日志级别：debug / info / warning / error	info

APISIX 连接

变量	说明	默认值
APISIX_BASE_URL	Admin API 地址，格式 scheme://host[:port]	http://localhost:9180
APISIX_ADMIN_KEY	必填。映射到 X-API-KEY 请求头	-
APISIX_API_VERSION	响应格式：auto（自动探测）/ v2 / v3	auto
APISIX_READ_ONLY	只读模式（禁用写工具）	true
APISIX_TIMEOUT	请求超时秒数	30
APISIX_INSECURE	跳过 TLS 证书验证（自签名 / 内部 CA 场景）	false

只读模式

默认开启，写工具（create / update / toggle）不注册，Agent 看不到也调不到。开启写操作：

{ "env": { "APISIX_READ_ONLY": "false" } }

响应格式探测

APISIX_API_VERSION=auto（默认）时，从成功响应（2xx）中自动探测：优先读取 X-API-VERSION 响应头，头缺失时按响应体结构推断（node+action → v2，list+total → v3）。探测未完成前按 v3 处理。可强制指定 v2 或 v3 跳过探测。

探测结果在进程生命周期内缓存，不主动失效。若 APISIX 实例重启并切换了配置，需重启 MCP 进程。

TLS 证书验证

默认验证 TLS 证书（行为与 httpx 一致）。自签名或内部 CA 环境：

{ "env": { "APISIX_INSECURE": "true" } }

禁用证书验证不安全，生产环境应使用受信任 CA 签发的有效证书。

多协议传输

协议	端点	适用
stdio（默认）	-	本地客户端集成（Claude Code、Cursor 等）
sse	http://<host>:<port>/sse	SSE 传输（已废弃）
streamable-http	http://<host>:<port>/mcp	远程部署 / 多客户端共享

启动示例：

MCP_TRANSPORT=streamable-http \
MCP_HOST=0.0.0.0 MCP_PORT=8000 \
MCP_AUTH_TOKEN=your-strong-token \
APISIX_BASE_URL=http://localhost:9180 \
APISIX_ADMIN_KEY=your-admin-key \
mcp-apisix

接口认证

MCP_AUTH_TOKEN 非空时，HTTP 请求需携带：

Authorization: Bearer <MCP_AUTH_TOKEN>

兼容 X-Auth-Token / X-MCP-Token 请求头。GET /health 免鉴权（容器探活）。

stdio 不经过网络，不做 Token 认证。未设 MCP_AUTH_TOKEN 时 HTTP 接口不鉴权，生产环境务必配置。

MCP Resources

URI	说明
apisix://server-info	APISIX 服务器环境信息（响应格式 v2/v3、可用能力清单）

会话建立时探测层尚无数据，Resource 返回配置值 + 探测状态"未知"；首次调用 Admin API 后探测完成，后续读取返回准确格式。每次读取动态返回，非静态快照。

Stateless HTTP 模式

MCP_STATELESS_HTTP=true：每次请求独立处理，不保留会话状态。适配 Serverless（AWS Lambda、阿里云函数计算）或多副本部署。

MCP_TRANSPORT=streamable-http \
MCP_STATELESS_HTTP=true \
MCP_HOST=0.0.0.0 MCP_PORT=8000 \
mcp-apisix

Stateless 模式不支持 SSE 流式响应，每个 HTTP 请求独立完成后返回。

容器化部署

本地构建（Docker）

docker build -t mcp-apisix:latest .

docker run -d --name mcp-apisix -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_AUTH_TOKEN=your-strong-token \
  -e APISIX_BASE_URL=http://your-apisix-host:9180 \
  -e APISIX_ADMIN_KEY=your-admin-key \
  -e APISIX_READ_ONLY=false \
  mcp-apisix:latest

Docker Compose

cp .env.example .env   # 按需修改
docker compose up -d

docker-compose.yml 已内置：基于 Dockerfile 构建（标记为 mcp-apisix:latest）、/health 健康检查、非 root 用户运行。

跳过本地构建、直接拉取公开镜像：删除 build: 段，只保留 image: ghcr.io/zhouweico/mcp-apisix:latest。

使用示例

下面示例均为自然语言提示，AI 助手会自动映射到对应 MCP 工具。

资源查询

列出 APISIX 里所有的路由（只看 id、name、uri）

查看路由 r1 的完整配置

列出所有上游，按名称过滤包含 "user-service" 的

查看消费者 alice 的配置

列出所有全局规则，返回完整配置

语义查询

APISIX 支持哪些插件？按优先级列出来

查看 key-auth 插件的 schema，需要哪些字段

当前 APISIX 实例返回的是 v2 还是 v3 格式？支持引用过滤吗？

配置校验

帮我校验这份路由配置是否符合 schema：
{"uri": "/api/v1/*", "upstream": {"type": "roundrobin", "nodes": {"127.0.0.1:8080": 1}}}

写操作（需 APISIX_READ_ONLY=false）

创建一个路由，uri 是 /api/v1/users，转发到 upstream u1

更新路由 r1，把 priority 改成 100

禁用路由 r1

创建一个上游，类型 roundrobin，节点 127.0.0.1:8080 权重 1

更新上游 u1，把超时改成 10 秒

创建一个服务，绑定 upstream u1，开启 key-auth 插件

写操作属破坏性操作，支持 Elicitation 的客户端会弹出二次确认；stdio 等不支持的客户端直接执行，返回结果中标注"未经人工确认"。

字段投影

列出所有路由，只返回 id、name、uri、upstream_id 这几个字段

列出路由的完整配置（不要裁剪字段）

labels 为强制保留字段，任何投影都会包含（用于识别资源归属）。

只读模式（APISIX_READ_ONLY=true）

写工具在只读模式下不注册，AI 只能执行查询类操作：

只读模式下：帮我禁用路由 r1

AI 会回复该操作不可用，引导用户关闭只读模式或手动处理。

License

MIT