Tplink Omada MCP

TP-Link Omada MCP服务器

## 🤖 人工智能开发库 自从 2026年3月2日，此存储库不包含人工编写的代码。 所有的规划、开发和代码审查都是由AI代理执行的。人类仍然处于方向、决策和最终批准的循环中——但每一行代码、每一次测试、每一个提交和每一个PR都是人工智能的工作。 这不是一个实验。这就是它现在的工作方式。 了解更多

______________________________________________________________________

一个用TypeScript实现的模型上下文协议（MCP）服务器，它将TP-Link Omada控制器API暴露给AI副驾驶和自动化工作流。服务器根据控制器进行身份验证，列出站点、设备和连接的客户端，并提供通用工具来调用任意Omada API端点。

兼容性： 使用Omada控制器5.x和6.x版本进行测试

快速开始

与克劳德桌面（stdio）一起使用

1. 拉取Docker镜像 （或在本地构建 npm run docker:build):

   docker pull jmtvms/tplink-omada-mcp:latest

1. 将MCP服务器添加到Claude Desktop配置中.编辑您的Claude Desktop配置文件：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json

1. 添加以下配置:

   {
     "mcpServers": {
       "tplink-omada": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e", "OMADA_BASE_URL=https://your-omada-controller.local",
           "-e", "OMADA_CLIENT_ID=your-client-id",
           "-e", "OMADA_CLIENT_SECRET=your-client-secret",
           "-e", "OMADA_OMADAC_ID=your-omadac-id",
           "-e", "OMADA_SITE_ID=your-site-id",
           "-e", "OMADA_STRICT_SSL=false",
           "jmtvms/tplink-omada-mcp:latest"
         ]
       }
     }
   }

将环境变量值替换为实际的Omada控制器凭据。

1. 重新启动克劳德桌面 加载新的MCP服务器配置。

1. 验证连接 请Claude列出您的Omada网站或设备。

使用Docker容器

CLI/stdio容器

docker run -it --rm \
  --env-file .env \
  jmtvms/tplink-omada-mcp:latest

HTTP服务器容器

docker run -d \
  --env-file .env \
  -e MCP_SERVER_USE_HTTP=true \
  -e MCP_HTTP_BIND_ADDR=0.0.0.0 \
  -p 3000:3000 \
  jmtvms/tplink-omada-mcp:latest

HTTP服务器将在 http://localhost:3000/mcp.

特性

• OAuth客户端凭据身份验证，带有自动令牌刷新功能
• 用于检索站点、网络设备和连接客户端的工具
• 用于高级自动化场景的通用Omada API调用程序
• 环境驱动配置
• 存储在下的每个标签的Omada OpenAPI引用 docs/openapi
• 即用型devcontainer，附带Omada控制器服务

入门

先决条件

• Docker（用于运行预构建的容器）或Node.js 24+（用于本地开发）
• 访问TP-Link Omada控制器（例如使用 mbentley/omada-controller Docker镜像）

配置

MCP服务器从环境变量中读取其配置。看 .env.example 以获取完整的参考。

工具类别筛选

每个令牌都是 [:].权限后缀：

类别参考

标记为的类别 * 为即将到来的阶段保留，目前还没有工具实现。指定它们将产生启动警告，并将跳过它们。写入工具目前仅限于 clients 类别。

组别名扩展到其组中的所有类别：

示例：

# Read-only access to everything
OMADA_TOOL_CATEGORIES=all:r

# Default safe subset (read only)
OMADA_TOOL_CATEGORIES=dashboard:r,client-insights:r,clients:r,devices-all:r

# Full access including write operations
OMADA_TOOL_CATEGORIES=all:rw

# Network read + client write operations
OMADA_TOOL_CATEGORIES=network-all:r,clients:rw

Omada客户端配置

MCP通用服务器配置

会话ID和身份验证： 当 OMADA_CLIENT_ID, OMADA_CLIENT_SECRET，以及 OMADA_OMADAC_ID 如果提供了（默认客户端凭据模式），服务器将无状态运行并处理 Mcp-Session-Id 标题为可选。未来基于OAuth的用户身份验证模式将再次需要此标头。

MCP服务器HTTP配置

这些变量仅在以下情况下使用 MCP_SERVER_USE_HTTP=true:

创建一个 .env 文件（被git忽略）或在启动服务器之前导出变量。

发展

npm run dev

开发模式通过实时重新加载支持来保持TypeScript服务器运行 tsx.

建筑

npm run build

代码检查

npm run check

测试

单元测试

npm test               # run all unit tests
npm run test:watch     # watch mode
npm run test:coverage  # with coverage report

覆盖阈值：

集成测试（Docker）

尚未实施——本节记录了 计划的 跟踪集成测试策略 #57 和 #58.

集成测试将在Docker容器中针对真实的Omada软件控制器运行。他们是 不 计划在每个PR上运行——它们是一个里程碑式的发布门户，也是编写工具的测试工具。

规划布局：

• test/docker/ （组合+快照/种子工具）
• tests/integration/
• npm run test:integration

⚠️ 第二阶段的写工具必须只针对Docker控制器进行测试，而不能针对生产控制器进行测试。

运行MCP服务器

npm start

MCP服务器通过标准输入和输出进行通信。通过参考以下内容将其与MCP兼容客户端集成 npm start 命令并提供所需的环境变量。

Docker镜像

提供容器映像以运行MCP服务器：

npm run docker:build  # Build the Docker image (tag: jmtvms/tplink-omada-mcp:latest)
npm run docker:run    # Launch the container with your .env file
npm run docker:push   # Push the image to Docker Hub

你也可以直接从Docker Hub中提取预构建的镜像：

docker pull jmtvms/tplink-omada-mcp:latest

同一映像支持stdio和HTTP传输-使用环境变量（例如set）配置所需的模式 MCP_SERVER_USE_HTTP=true 用于HTTP模式）。

使用MCP检查器进行调试

使用MCP检查器在不离开浏览器的情况下交互式测试工具、资源和提示。检查器会自动适应您的 .env 配置：

• npm run inspector --根据您的 .env 设置：

- 如果 MCP_SERVER_USE_HTTP=false （或未设置）：在stdio模式下运行服务器 tsx src/index.ts 用于实时重新加载调试 - 如果 MCP_SERVER_USE_HTTP=true：在配置的端口/传输上连接到已运行的HTTP服务器（首先使用以下命令启动服务器 npm run dev)

• npm run inspector:build --首先编译项目，然后对生产构建启动检查器(dist/index.js)以验证释放奇偶性。还基于以下内容适应stdio或HTTP模式 .env.

要求： 检查员要求 .env 存储库根目录下的文件。它将同时加载 .env 和 .env.local （如果存在）以确定服务器模式、端口、传输和路径。

MCP Inspector工具会自动绑定到localhost并生成用于身份验证的会话令牌（打印到控制台并自动填写在浏览器URL中）。

传输协议

MCP服务器使用 可流式传输的HTTP 运输，实现 MCP协议版本2025-03-26.

export MCP_SERVER_USE_HTTP=true
npm run dev

特征：

• 所有操作（GET、POST、DELETE）的单一端点
• 服务器发送流式响应事件
• 使用加密会话ID的内置会话管理（服务器在使用客户端凭据时当前无状态运行）

端点默认为 /mcp 手柄：

• GET /mcp -建立SSE流并初始化会话
• POST /mcp -发送JSON-RPC消息
• DELETE /mcp -终止会话

安全注意事项

默认情况下启用DNS重新绑定保护：

• 原产地验证：服务器验证 Origin 所有传入连接上的标头。配置允许的来源 MCP_HTTP_ALLOWED_ORIGINS （默认值： 127.0.0.1, localhost).使用 * 允许所有来源（仅用于开发，不建议用于生产）。
• 网络绑定：服务器绑定到 127.0.0.1 默认情况下，仅限制对localhost的访问。集 MCP_HTTP_BIND_ADDR=0.0.0.0 将服务器暴露到您的网络中（不建议在没有额外安全措施的情况下用于生产）。

有关MCP协议和传输的更多信息，请参阅 模型上下文协议文档.

HTTP传输使用情况

使用以下命令启动HTTP传输：

# Start with HTTP enabled
export MCP_SERVER_USE_HTTP=true
npm run dev    # live reload during development
npm run start  # run the compiled output

默认情况下，服务器会监听 127.0.0.1:3000 并在以下位置暴露MCP端点 /mcp 进行健康检查 /healthz.使用可选配置绑定地址、端口和路径 MCP_HTTP_* 环境变量记录在 .env.exampleThe npm run docker:run:http helper包装HTTP映像并自动发布端口。

使用ngrok

要与远程工具共享本地服务器，可以使用ngrok公开HTTP服务器。

选项1：内置ngrok支持（推荐）

设置以下环境变量：

export MCP_HTTP_NGROK_ENABLED=true
export MCP_HTTP_NGROK_AUTH_TOKEN=your-ngrok-auth-token
npm run dev

服务器将自动建立ngrok隧道并记录公共URL。

选项2：手动ngrok设置

启动服务器后，在单独的终端中运行ngrok：

ngrok http 3000

这会将公共HTTPS URL转发到 http://localhost:3000 并在控制台中打印隧道地址。

在客户端凭据模式下，服务器已经处理 Mcp-Session-Id 可选；如果在传输过程中删除了标头，请求仍然会成功。

工具

现场和客户

设备

网络

防火墙和ACL

防火墙流量和QoS

防火墙IDS/IPS

安全与威胁管理

仪表板/监视器

洞察

虚拟专用网络

档案

日志

控制器

维护

帐户用户

账户云

日程表

支持的Omada API操作

Devcontainer支持

该存储库包括一个即用型 开发容器 配置一个专用的Omada控制器sidecar，用于本地开发和测试。看 .devcontainer/README.md 了解详情。

许可证

该项目根据 MIT许可证.