mcp-apollo

Apollo MCP Server - 让 AI 助手能够查询和管理 Apollo 配置中心的配置。

基于 Apollo Portal 开放平台 OpenAPI（/openapi/v1/...，参见 OpenAPI 接口文档），支持配置的读取与发布。

特性

• 多协议传输：stdio（默认）、sse、streamable-http，一套代码适配本地与远程场景
• 接口认证：HTTP 传输支持 Bearer Token 保护，未授权请求返回 401
• Apollo 原生概念：直接以 env / app / cluster / namespace / item 组织配置，读写一体
• 写前确认：全部 8 个写操作在执行前通过 MCP 2.0 Elicitation 弹出确认表单，提示中展示配置项 key、环境、应用等操作目标，需用户明确同意后才执行
• MCP Resources：以 apollo:// URI 暴露应用列表、环境集群、命名空间等只读元数据，客户端可直接读取
• Stateless HTTP：支持无状态 HTTP 模式，每次请求独立处理、无会话状态，适合 Serverless / 多副本部署
• 灵活部署：uvx 免安装运行、Docker 公开镜像即拉即用、或本地构建

前置准备

在 Apollo Portal 的「开放平台」中创建第三方应用并生成 Token，并为其授权目标 App / 环境 / 命名空间。你需要准备：

• Apollo Portal 地址（如 http://localhost:8070）
• OpenAPI Token
• 目标应用的 appId

快速开始

MCP 客户端（stdio，本地）

以 Claude Code 为例，在项目 .mcp.json 或全局 ~/.claude.json 中添加：

{
  "mcpServers": {
    "apollo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-apollo"],
      "env": {
        "APOLLO_PORTAL_URL": "http://localhost:8070",
        "APOLLO_TOKEN": "your-openapi-token",
        "APOLLO_APP_ID": "your-app-id",
        "APOLLO_ENV": "DEV",
        "APOLLO_CLUSTER": "default",
        "APOLLO_NAMESPACE": "application",
        "APOLLO_READ_ONLY": "false"
      }
    }
  }
}

APOLLO_READ_ONLY 默认为 true（仅注册只读工具）。上例显式设为 false 以开启 8 个写工具； 若只需查询，删掉该项即可。

Cursor、OpenCode、Claude Desktop 等客户端的配置格式相同，核心均为 command: uvx + args: ["mcp-apollo"]，按各客户端语法填入 APOLLO_* 环境变量即可。

Docker（公开镜像，免构建）

已发布公开镜像 ghcr.io/zhouweico/mcp-apollo:latest，无需本地构建。下面以 Claude Code 为例。

方式一：stdio（由客户端拉起容器，适合本地集成）

{
  "mcpServers": {
    "apollo": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/zhouweico/mcp-apollo:latest"],
      "env": {
        "APOLLO_PORTAL_URL": "http://your-apollo-portal:8070",
        "APOLLO_TOKEN": "your-openapi-token",
        "APOLLO_APP_ID": "your-app-id",
        "APOLLO_ENV": "DEV"
      }
    }
  }
}

必须带 -i（保持 stdin 管道），否则容器内的 stdio 服务无法与客户端通信。

方式二：HTTP + 认证（容器独立运行，客户端远程连接，适合多客户端共享）

先启动容器：

docker run -d -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_AUTH_TOKEN=your-strong-token \
  -e APOLLO_PORTAL_URL=http://your-apollo-portal:8070 \
  -e APOLLO_TOKEN=your-openapi-token \
  -e APOLLO_APP_ID=your-app-id \
  ghcr.io/zhouweico/mcp-apollo:latest

再在 Claude Code 的 .mcp.json 中通过 HTTP 连接：

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

可用工具

全部 16 个工具完整覆盖 Apollo OpenAPI 文档「3.2 API接口列表」 的 17 个接口（其中 apollo_get_config 一个工具同时覆盖 3.2.6 与 3.2.9，故工具数为 16、接口数为 17）。

apollo_get_config 参数

分页为客户端侧分页：Apollo OpenAPI 的 GET namespace 一次返回全部配置项， 本项目在客户端按 page/page_size 切片，避免大命名空间一次性输出过多内容。指定 key 时分页参数被忽略。

只读 / 写的区别：上表「类型 = 只读」的 8 个工具始终可用； 「类型 = 写」的 8 个工具（create/update/delete/releases/cluster/namespace/app/rollback） 在默认的只读模式（APOLLO_READ_ONLY=true）下会被完全排除——不出现在 tools/list 中， Agent 既看不到也无法调用（注册期排除，非运行期拦截）。需要写能力时显式设 APOLLO_READ_ONLY=false。

写入与发布分两步：先用 apollo_create_item / apollo_update_item / apollo_delete_item 落配置项， 再用 apollo_releases 发布使其对所有客户端生效。写操作均受 APOLLO_READ_ONLY 控制。

写前确认：全部 8 个写工具在执行前都会通过 MCP 2.0 Elicitation 弹出确认表单， 提示中展示操作目标（配置项 key、集群名、env / app / cluster / ns 作用域），未显式传入的作用域参数显示为「默认」。 删除与回滚会额外标注「不可撤销」。若客户端未声明 elicitation 能力，SDK 直接返回 -32021 拒绝调用， 写工具不会执行（不降级放行）。如需在非交互环境写入，请直接调用 Apollo OpenAPI。

配置

环境变量

MCP 传输与认证

Apollo 连接

env / app_id / cluster_name / namespace_name 为 Apollo OpenAPI 路径参数（接口层必填）；本 MCP 工具允许省略，省略时回退对应 APOLLO_* 环境变量，其中 env/cluster/namespace 未配置用内置默认 DEV/default/application；app_id 无内置默认值，须由参数或 APOLLO_APP_ID 提供，否则报错。

Apollo 概念说明

Apollo 的配置组织层级为：环境（env）> 应用（app）> 集群（cluster）> 命名空间（namespace）> 配置项（item，key/value）。

• properties 格式的命名空间：每个 key/value 是一个独立配置项。
• 非 properties 格式（yaml/json/xml/txt）：整份内容存放在固定 key content 下。写入时用 apollo_create_item 传 key=content、整份内容作为 value；再调用 apollo_releases 发布（已存在则改用 apollo_update_item）。

只读模式

默认即只读（APOLLO_READ_ONLY=true）：8 个写工具不注册，tools/list 中不可见，Agent 无法调用。

需要写能力时显式关闭：

{
  "env": {
    "APOLLO_READ_ONLY": "false"
  }
}

TLS 证书验证

本服务基于 httpx2 发起 HTTPS 请求，默认会验证 TLS 证书（行为与 httpx 一致）。

• 在使用自签名证书或内部 CA 的环境中，HTTPS 请求会因证书校验失败而报错。此时可设置环境变量 APOLLO_INSECURE=true 跳过 TLS 证书验证。
• 该选项适用于开发、测试等使用自签名证书的环境。

{
  "env": {
    "APOLLO_INSECURE": "true"
  }
}

安全警告：禁用 TLS 证书验证是不安全的，会使得 HTTPS 连接容易受到中间人攻击。请勿在生产环境中使用，生产环境应使用受信任的 CA 签发的有效证书。

多协议传输

通过 MCP_TRANSPORT 选择传输协议：

• stdio（默认）：标准输入输出，适合 Claude Code、Cursor 等本地 AI 客户端集成。
• sse：Server-Sent Events，HTTP 传输，端点 http://<host>:<port>/sse。
• streamable-http：Streamable HTTP，端点 http://<host>:<port>/mcp。

以 streamable-http 启动示例：

MCP_TRANSPORT=streamable-http \
MCP_HOST=0.0.0.0 MCP_PORT=8000 \
MCP_AUTH_TOKEN=your-strong-token \
mcp-apollo

接口认证

设置 MCP_AUTH_TOKEN 后，所有 HTTP 请求必须携带正确 Token，否则返回 401：

Authorization: Bearer <MCP_AUTH_TOKEN>

也兼容 X-Auth-Token / X-MCP-Token 请求头。健康检查端点 GET /health 免鉴权，返回 {"status":"ok"}，用于容器探活。

stdio 传输为本地进程通信，不涉及网络，无需也不会进行 Token 认证。未设置 MCP_AUTH_TOKEN 时 HTTP 接口不鉴权，生产环境请务必配置。

注意区分两类 Token：MCP_AUTH_TOKEN 保护本 MCP Server 的 HTTP 接口；APOLLO_TOKEN 用于访问 Apollo OpenAPI，两者互不相关。

MCP Resources

本服务以 MCP 2.0 Resources 暴露只读元数据，客户端可直接通过 URI 读取，无需调用工具：

Resources 仅暴露只读数据，不涉及任何写操作。

Stateless HTTP 模式

设置 MCP_STATELESS_HTTP=true 可启用无状态 HTTP 模式，每次请求独立处理、不保留会话状态，适合 Serverless 平台（如 AWS Lambda、阿里云函数计算）或多副本无状态部署：

MCP_TRANSPORT=streamable-http \
MCP_STATELESS_HTTP=true \
MCP_PORT=8000 \
mcp-apollo

Stateless 模式下不支持流式响应（SSE stream），每个 HTTP 请求独立完成工具调用后返回。适合短时、无状态的工具调用场景。

容器化部署

本地构建（Docker）

# 构建镜像
docker build -t mcp-apollo:latest .

# 以 streamable-http 运行并启用认证
docker run -d --name mcp-apollo -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_AUTH_TOKEN=your-strong-token \
  -e APOLLO_PORTAL_URL=http://your-apollo-portal:8070 \
  -e APOLLO_TOKEN=your-openapi-token \
  -e APOLLO_APP_ID=your-app-id \
  -e APOLLO_ENV=DEV \
  -e APOLLO_CLUSTER=default \
  -e APOLLO_NAMESPACE=application \
  mcp-apollo:latest

直接拉取已发布的公开镜像、免本地构建的用法见 快速开始 → Docker。

Docker Compose

复制 .env.example 为 .env 并按需修改，然后：

cp .env.example .env
docker compose up -d

docker-compose.yml 已内置 build（基于本地 Dockerfile 构建并标记为 mcp-apollo:latest）和健康检查（探测 /health），以非 root 用户运行，适合本地开发部署。

若想直接运行已发布的公开镜像、跳过本地构建，可将 docker-compose.yml 中的 build: 段删除，仅保留 image: ghcr.io/zhouweico/mcp-apollo:latest。

使用场景示例

配置好后，你可以这样和 AI 对话：

查询配置：

帮我获取 Apollo 中 application 命名空间的所有配置项

查看 redis 命名空间里 key 为 timeout 的配置，环境是 PRO

获取 app-id 为 order-service 的 gateway 命名空间配置，集群是 default

列出 order-service 在 DEV 环境下的所有 Namespace

查看 application 命名空间最近一次发布的内容

分页查看 application 命名空间第 2 页的配置项（每页 50 条）

发布配置：

把 application 命名空间的 timeout 改成 3000 并发布

在 redis 命名空间新增配置项 max-connections=100，环境 DEV

把下面这段 yaml 作为 content 发布到 order-service 的 application.yaml 命名空间：
server:
  port: 6379

License

MIT