内容
# Meraki MCP 服务器
[](https://github.com/wyre-technology/meraki-mcp/actions/workflows/release.yml)
[](https://opensource.org/licenses/Apache-2.0)
[](https://nodejs.org/)
一个 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，为 AI 助手提供结构化的访问权限，通往 [Cisco Meraki Dashboard](https://developer.cisco.com/meraki/api-v1/) —— 组织、网络、设备、客户端、无线、交换和设备操作。
> **注意：** 该项目由 [Wyre Technology](https://github.com/wyre-technology) 维护。
## 快速入门
**Claude 代码（CLI）：**
```bash
claude mcp add meraki-mcp \
-e MERAKI_API_KEY=您的 API 密钥 \
-e MERAKI_ORG_ID=您的组织 ID \
-- npx -y github:wyre-technology/meraki-mcp
```
参见 [安装](#安装) 以了解 Docker 和从源码构建的方法。
## 功能
- **🔌 MCP 协议合规性**：完全支持通过 stdio 和 HTTP 传输的 MCP 工具
- **🌐 网络覆盖**：涵盖组织、网络、设备、客户端、无线、交换和设备（MX）操作的工具
- **🔍 简化导航**：`meraki_navigate` 和 `meraki_status` 是无状态的发现辅助工具 —— 任何工具都可以在任何时候调用
- **🛟 默认安全**：只读模式 **默认开启**；写入操作需要显式确认，且破坏性操作需要显式确认
- **🖼️ 交互式设备卡（MCP 应用）**：`meraki_devices_get` 在 MCP 应用主机（SEP-1865）中渲染为只读交互式卡 —— 默认中立，可通过 `window.__BRAND__` 注入或 `MCP_BRAND_*` 环境变量进行品牌定制
- **🧰 长尾逃生通道**：`meraki_raw_request` 可访问任何 Meraki v1 端点（不被精选工具覆盖）
- **🐳 准备好 Docker**：容器化部署，支持 HTTP 传输和健康检查
- **📊 结构化日志记录**：可配置的日志级别
## 安装
### 选项 1：Docker
```bash
docker run -d \
-e MERAKI_API_KEY=您的密钥 \
-e MERAKI_ORG_ID=您的组织 ID \
-p 8080:8080 \
ghcr.io/wyre-technology/meraki-mcp:latest
```
### 选项 2：从源码构建
```bash
git clone https://github.com/wyre-technology/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_PORT` | HTTP 服务器端口 | `8080` |
| `AUTH_MODE` | 身份验证模式（`env` 或 `gateway`） | `env` |
| `LOG_LEVEL` | 日志级别（`debug`、`info`、`warn`、`error`） | `info` |
> 旧的 `READ_ONLY` 变量也受尊重；`READ_ONLY_MODE` 优先级更高。
## 安全模型
该服务器默认为 **只读模式**。除非您显式设置 `READ_ONLY_MODE=false`，否则写入操作（更新、重启、删除）将被阻止。
- **读取工具**（`*_list`、`*_get`）始终可用。
- **高影响写入**（例如 `meraki_networks_update`、`meraki_devices_reboot`、`meraki_wireless_ssids_update`）受只读模式限制。
- **破坏性工具**（`meraki_networks_delete`、`meraki_devices_remove`）还需要 `confirm_destructive_action: true` 参数。确认标志永远不会转发到 Meraki API。
- **`meraki_raw_request`** 逃生通道根据 HTTP 方法分类调用：`GET` 是读取操作；`POST`/`PUT`/`DELETE` 是写入操作；`DELETE` 是破坏性操作。
## 领域
所有工具都提前返回。使用 `meraki_navigate` 探索领域的工具，或使用 `meraki_status` 检查连接性和配置的组织。
| 领域 | 工具 |
| --- | --- |
| **组织** | `meraki_organizations_list`、`meraki_organizations_get`、`meraki_organizations_inventory_list` |
| **网络** | `meraki_networks_list`、`meraki_networks_get`、`meraki_networks_update` ⚠、`meraki_networks_delete` ⚠⚠ |
| **设备** | `meraki_devices_list`、`meraki_devices_get`、`meraki_devices_reboot` ⚠、`meraki_devices_remove` ⚠⚠ |
| **客户端** | `meraki_clients_list`、`meraki_clients_get`、`meraki_clients_get_policy`、`meraki_clients_update_policy` ⚠ |
| **无线** | `meraki_wireless_ssids_list`、`meraki_wireless_ssids_update` ⚠、`meraki_wireless_rf_profiles_list` |
| **交换机** | `meraki_switch_ports_list`、`meraki_switch_ports_update` ⚠、`meraki_switch_port_statuses_list` |
| **设备** | `meraki_appliance_firewall_l3_get`、`meraki_appliance_firewall_l3_update` ⚠、`meraki_appliance_vpn_status_get` |
| **（长尾）** | `meraki_raw_request` |
⚠ = 高影响写入 · ⚠⚠ = 破坏性 / 不可逆
## Docker 部署
复制 `.env.example` 到 `.env` 并填写您的凭证：
```bash
cp .env.example .env
# 编辑 .env 文件，填写您的 Meraki API 密钥（和组织 ID）
docker run --env-file .env -p 8080:8080 ghcr.io/wyre-technology/meraki-mcp:latest
```
## 开发
```bash
npm ci
npm run build # 构建项目
npm run start # 在 stdio 上运行
npm run start:http # 运行 HTTP 传输
npm run test # 运行测试
```
## 测试
```bash
npm test
```
测试套件涵盖安全合同：只读强制执行、破坏性确认，以及 `confirm_destructive_action` 永远不会转发到 SDK。
## 许可证
Apache 2.0 —— 版权归 WYRE Technology 所有
