Cisco Meraki

Meraki MCP 服务

一个 Model Context Protocol (MCP) 服务，为 AI 助手提供对 Cisco Meraki Dashboard 的结构化访问能力，涵盖组织、网络、设备、客户端、无线、交换和安全设备操作。

注意： 本项目由 Wyre Technology 维护。

快速开始

Claude Code（命令行）：

claude mcp add meraki-mcp \
  -e MERAKI_API_KEY=your-api-key \
  -e MERAKI_ORG_ID=your-org-id \
  -- npx -y github:WYRE-AI/meraki-mcp

Docker 和从源代码安装的方法，请参阅安装。

功能

• 🔌 MCP 协议兼容性：全面支持通过 stdio 和 HTTP 传输的 MCP 工具
• 🌐 网络覆盖范围：提供涵盖组织、网络、设备、客户端、无线、交换和安全设备（MX）操作的工具
• 🔍 扁平化导航：meraki_navigate 和 meraki_status 是无状态的发现辅助工具，所有工具都可随时调用
• 🛟 默认安全：只读模式默认开启；写入操作受限，破坏性操作需要明确确认
• 🖼️ 交互式设备卡片（MCP Apps）：在 MCP Apps 宿主中，meraki_devices_get 会呈现为只读交互式卡片（SEP-1865）；默认采用中性色，可通过注入 window.__BRAND__ 或使用 MCP_BRAND_* 环境变量进行品牌定制
• 🧰 长尾需求扩展接口：meraki_raw_request 可访问精选工具未涵盖的任意 Meraki v1 端点
• 🐳 支持 Docker：容器化部署，提供 HTTP 传输和运行状况检查
• 📊 结构化日志：可配置日志级别

安装

选项 1：Docker

镜像会在容器内监听 0.0.0.0，并设置 AUTH_MODE=gateway。将端口发布到环回地址，并传入服务间密钥。在网关模式下，每个请求都会通过 X-Meraki-Api-Key 传入 API 密钥。

docker run -d \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/meraki-mcp:latest

选项 2：从源代码安装

git clone https://github.com/WYRE-AI/meraki-mcp.git
cd meraki-mcp
npm ci
npm run build

配置

变量	说明	默认值
MERAKI_API_KEY	Meraki Dashboard API 密钥	—
MERAKI_ORG_ID	默认组织 ID（可选）	—
MERAKI_BASE_URL	覆盖 Meraki API 基础 URL（可选）	—
READ_ONLY_MODE	安全开关；设为 true 时会阻止所有写入操作	true
MCP_TRANSPORT	传输模式（stdio 或 http）	stdio
MCP_HTTP_HOST	配置密钥时使用的绑定地址。未设置时绑定到 127.0.0.1。容器镜像会设置为 0.0.0.0。	127.0.0.1
MCP_HTTP_PORT	HTTP 服务端口	8080
AUTH_MODE	env 从环境中读取 MERAKI_*。gateway 要求每个 /mcp 请求都携带 X-Meraki-Api-Key。镜像和 Compose 会设置为 gateway。	env
CONDUIT_S2S_SECRET	服务间密钥。启动 HTTP 必须提供此项。空值和已知占位符值会被拒绝。切勿提交真实值。	—
MCP_ALLOW_INSECURE_DEV	设为 1 可在未配置 CONDUIT_S2S_SECRET 时使用本地 HTTP。此时会记录警告、跳过 X-Gateway-S2S，且仅监听 127.0.0.1。	—
LOG_LEVEL	日志级别（debug、info、warn、error）	info

同样支持旧版 READ_ONLY 变量；READ_ONLY_MODE 的优先级更高。

HTTP 身份验证

MCP_TRANSPORT=http 需要设置 CONDUIT_S2S_SECRET。如果该变量为空或是已知占位值（changeme、change-me、placeholder、secret、example、replace-me、s2s-secret、your-secret、your-s2s-secret、replace-with-a-real-secret），启动日志会记录错误并以非零状态退出。进程绝不会将密钥写入日志。设置 MCP_ALLOW_INSECURE_DEV=1 后，服务器会在未设置密钥的情况下启动、记录警告、跳过 X-Gateway-S2S，且仅监听 127.0.0.1——若 MCP_HTTP_HOST 设置为更宽泛的地址（例如 0.0.0.0），该设置会被忽略，并记录此覆盖行为。即使设置了该标志，仍会拒绝占位密钥。

未设置 MCP_HTTP_HOST 时，服务器会绑定到 127.0.0.1。设置密钥后，服务器会遵循 MCP_HTTP_HOST 的配置，包括 0.0.0.0。

设置密钥后，每个 /mcp 请求都必须包含 X-Gateway-S2S。其值为 t=<unix seconds>,v1=<hex>。v1 是对 ASCII 字符串 t=<unix seconds> 计算得到的 HMAC-SHA256，密钥为 CONDUIT_S2S_SECRET，并编码为小写十六进制。与服务器时钟相差超过 300 秒的时间戳会被拒绝。缺少或无效的标头会返回 401。

AUTH_MODE=gateway 还要求每个 /mcp 请求都包含 X-Meraki-Api-Key。X-Meraki-Org-Id 为可选项。这些标头是该请求的凭据来源。缺少 API 密钥会返回 401。

/health 仍无需身份验证，也不会读取供应商凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

X-Gateway-S2S 值示例（仅供说明；请使用真实密钥生成）：

t=1710000000,v1=<hmac-sha256 hex of "t=1710000000">

安全模型

此服务器默认采用只读模式。除非显式设置 READ_ONLY_MODE=false，否则会阻止写入操作（更新、重启、删除）。

• 读取工具（*_list、*_get）始终可用。
• 高影响写入操作（例如 meraki_networks_update、meraki_clients_update_policy）受只读模式限制。
• 需确认的工具还要求提供 confirm_destructive_action: true 参数，即使已设置 READ_ONLY_MODE=false 也不例外。确认标志绝不会转发给 Meraki API。以下两类工具符合此条件：
  • 不可逆操作——meraki_networks_delete、meraki_devices_remove。
  • 影响范围大——meraki_appliance_firewall_l3_update、meraki_switch_ports_update、meraki_wireless_ssids_update、meraki_devices_reboot。这些操作原则上可撤销，但每项操作都会通过可能被该更改中断的同一网络链路执行，因此操作人员可能失去撤销更改所需的连接。meraki_appliance_firewall_l3_update 还会替换规则集——载荷中未包含的规则都会被删除；而当 PSK 或身份验证模式发生变化时，meraki_wireless_ssids_update 会断开 SSID 上所有客户端的连接。
• 确认不能绕过只读模式：启用 READ_ONLY_MODE 时，即使调用已确认，仍会被阻止。
• meraki_raw_request 逃生口根据 HTTP 方法对调用进行分类：GET 属于读取操作；POST/PUT/DELETE 属于写入操作；DELETE 属于破坏性操作。

域

所有工具都会预先返回。使用 meraki_navigate 探索某个域的工具，或使用 meraki_status 检查连接状态和已配置的组织。

域	工具
organizations	meraki_organizations_list、meraki_organizations_get、meraki_organizations_inventory_list
networks	meraki_networks_list、meraki_networks_get、meraki_networks_update ⚠、meraki_networks_delete ⚠⚠
devices	meraki_devices_list、meraki_devices_get、meraki_devices_reboot ⚠⚠、meraki_devices_remove ⚠⚠
clients	meraki_clients_list、meraki_clients_get、meraki_clients_get_policy、meraki_clients_update_policy ⚠
wireless	meraki_wireless_ssids_list、meraki_wireless_ssids_update ⚠⚠、meraki_wireless_rf_profiles_list
switch	meraki_switch_ports_list、meraki_switch_ports_update ⚠⚠、meraki_switch_port_statuses_list
appliance	meraki_appliance_firewall_l3_get、meraki_appliance_firewall_l3_update ⚠⚠、meraki_appliance_vpn_status_get
（长尾）	meraki_raw_request（执行 DELETE 时为 ⚠⚠）

⚠ = 高影响写入操作，受只读模式限制 · ⚠⚠ = 还需要设置 confirm_destructive_action: true

Docker 部署

将 .env.example 复制为 .env，并设置 CONDUIT_S2S_SECRET（openssl rand -hex 32）。示例文件中的密钥请留空。

Compose 会发布 127.0.0.1:8080:8080，在未设置 CONDUIT_S2S_SECRET 时拒绝启动，并以 AUTH_MODE=gateway 运行。该服务没有 MERAKI_API_KEY、MERAKI_ORG_ID 或 env_file，因此项目 .env 无法注入静态供应商凭据。Compose 会从环境中插入 CONDUIT_S2S_SECRET。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用环境中的 MERAKI_API_KEY：

docker run -d \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e MERAKI_API_KEY=your-key \
  -e MERAKI_ORG_ID=your-org-id \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/meraki-mcp:latest

开发

npm ci
npm run build       # Build the project
npm run start       # Run over stdio
# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http
# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 npm run start:http
npm run test        # Run tests

测试

npm test

测试套件涵盖安全契约：只读模式的强制执行、破坏性操作确认，以及绝不将 confirm_destructive_action 转发给 SDK。

许可证

Apache 2.0 — 版权所有 WYRE Technology