claude-project — netmiko MCP 服务器 + 技能

一个可直接复制的项目，通过 只读访问 路由器、交换机和防火墙（基于 SSH），借助模型上下文协议（Model Context Protocol）将能力赋予 AI 智能体。

它附带了两个组件以及两者之间的连接逻辑：

• mcps/mcp_server_netmiko.py —— 一个自包含的 MCP 服务器。内置十个工具，每条命令都会经过操作员定义的允许/拒绝列表验证，输出会通过 ntc-templates 解析为 JSON 格式，并且每一次尝试都会生成一个出错即关闭的审计轨迹。

• .claude/skills/netmiko/SKILL.md —— 该技能教会智能体何时使用这些工具、各平台 CLI 方言的样貌，以及如何理解拒绝响应。

此处不会向设备写入任何内容。允许列表采用默认拒绝策略——空列表意味着不允许任何操作——并且拒绝侧始终优先于允许侧。

所有操作都会进入审计轨迹，并且 netmiko.query_audit_trail 使其可以在对话中被查询："SW-CORE-01 上按日期执行的所有操作"、"最近 6 个操作"、"本周哪些命令被拒绝了"。由于本项目没有 UI，该工具是读取审计轨迹的唯一方式。

作者与来源

本项目由 Ed Scrimaglia 创作 —— edgardo.scrimaglia@gmail.com，Octupus。服务器、技能、配置模型和文档均是他的作品，是为 Niko 智能体 编写的，并以独立项目的形式打包于此。

它始于一个分支，并且这一起源得到了明确承认而非隐藏：出发点是 Kirk Byers 的工作，而项目已在其基础上大幅发展。当前拥有的内容——基于真实数据源的清单、凭据解析、三种部署形态、输出分页、审计轨迹、技能以及本文档——均非来自上游。

Kirk Byers 的两个上游项目：

• Netmiko —— 实际与设备通信的多厂商 SSH 库。

• netmiko_mcp —— 本项目 fork 而来的 MCP 服务器。其中一部分基本保持原样：安全核心（命令验证、通配符处理、允许/拒绝不对称性），有意保留为忠实移植，以便上游补丁仍可进行 diff 对比。这是一个工程决策，并不限制其余工作。

Related MCP server: Network MCP Server

关于 Niko

此服务器是为了 Niko 而编写的，Niko 是由 Ed Scrimaglia 在 Octupus 构建的 Neural Intelligence Knowledge Orchestrator AI 智能体。Niko 前端连接一组 MCP 服务器——真实数据源服务器、本服务器、Jira、发送邮件、创建文件等——以便操作员可以用自然语言提问，并从实际数据中获得答案：SoT 用于回答应该是什么，设备本身用于回答实际是什么。

在 Niko 内部，同一个文件的运行方式略有不同，这值得了解，因为它解释了代码中的一些情况：

• 服务器在 回环地址上通过 HTTP 运行，每个服务器一个端口，通过 mcps/mcp_config.json 中的 url / transport / local / env 声明——与下面描述的相同双轴配置，以 Niko 自身的格式表示。

• 通过应用进行安装，而非复制文件：上传会被验证，依赖关系从代码本身解析，安装失败时会回滚，而不会留下半个服务器。

每一个集成都是 带后备机制的可选导入，因此永远无需安装 niko。共有四处，以下是每处导入失败时的降级情况：

在 Niko 之外，没有丢失任何重要的东西：并发处理器解决的是此处不会出现的多进程单文件问题，而列表预算则修剪长负载，供拥有自身上下文核算的智能体使用。同一个文件，两个归宿，无需分支。

Fedele 是 Niko 的真实数据源，这就是为什么即使使用 NetBox 实例，SoT 变量仍带有 FEDELE_ 前缀。

许可证

本项目自身代码采用 MIT 许可证 —— 参见 LICENSE。

这是一个衍生作品，因此适用两种许可证，两个文件均随项目提供：

NOTICE 包含 Apache-2.0 §4(b) 要求的署名和修改说明。Netmiko 是一个普通的 MIT 依赖：导入而非打包，无需重新分发。

布局

claude-project/
├── .mcp.json                     # declares the server (project scope)
├── .env.example                  # → copy to .env with the SSH credentials
├── .claude/skills/netmiko/
│   └── SKILL.md                  # one directory per skill, file named SKILL.md
├── mcps/
│   └── mcp_server_netmiko.py     # NOT at the root: the server reads ../.env
├── config/netmiko/
│   ├── commands.yml              # allow/deny list — without it, a 16-command fallback applies
│   └── inventory.yml             # inventory in netmiko_tools format
├── logs/                         # netmiko-mcp.log + netmiko-audit.jsonl
├── mcpr/netmiko/                 # created on demand (0700): large outputs
├── LICENSE  LICENSE-APACHE-2.0  NOTICE
└── pyproject.toml

两条不可协商的规则：

1. 技能文件位于 .claude/skills/<name>/SKILL.md。 Claude Code 不会读取 skills/netmiko.md：它需要该目录和确切的文件名。

2. 服务器位于 mcps/ 目录中，而非根目录。 PARENT_DIR 是包含 .py 文件目录的父目录（mcp_server_netmiko.py:62），而 .env 文件就从该处读取。如果服务器位于根目录，则会在项目上一级目录查找 .env。

启动运行

uv venv --python 3.12
uv pip install -r <(uv pip compile pyproject.toml)   # or: uv sync
cp .env.example .env && $EDITOR .env                 # SSH credentials
# .mcp.json needs no editing: its paths are project-relative
claude                                               # approve the project server

在会话内部：/mcp 列出 10 个工具，/skills 确认技能已加载。首次检查无需连接网络：

netmiko MCP 执行的是哪个命令策略？

三种形态

清单来自何处以及凭据来自何处，是两个独立的维度。这就是为什么一个服务器可以支持三种部署形态——也是服务器无需为切换形态而修改的原因：两个环境变量决定一切。

netmiko.get_metadata 会报告实际运行的形态——切勿根据配置文件猜测：

{
  "inventory": {"backend": "fedele", "scope_filter": {"tag": "lab"}, "available": true},
  "credential_source": "env",
  "device_types_in_inventory": ["cisco_ios", "huawei_vrp", "…"]
}

A — Fedele 作为真实数据源，包含凭据

智能体通过名称请求设备；服务器在调用时根据 SoT 解析地址、平台和凭据。没有关于资产的信息存储在此项目中：向 SoT 添加设备后，下一次调用即可访问，无需编辑文件，也无需重启。

// .mcp.json → env
"NETMIKO_MCP_INVENTORY_TYPE": "fedele",
"NETMIKO_MCP_CREDENTIAL_SOURCE": "fedele",
"NETMIKO_MCP_FEDELE_GROUP_SOURCE": "tags",        // tags | device_roles | sites
"NETMIKO_MCP_FEDELE_DEVICE_FILTER": "tag=lab",    // the scope filter — read the warning
"NETMIKO_MCP_FEDELE_CACHE_TTL": "60"

# .env
FEDELE_URL=https://fedele.example.com
FEDELE_TOKEN=<API token>
FEDELE_CREDENTIALS_KEY=<Fernet key of the fedele_credentials plugin>

文件：无必需项。commands.yml 推荐使用——没有它时，内置的后备策略将生效。无需本地清单，也不需要 NETMIKO_USERNAME / NETMIKO_PASSWORD；当 credential_source=fedele 时，NETMIKO_SECRET 会被忽略——启用密码也来自 SoT。

凭据查找的工作方式，分为三步：

GET dcim/devices/?name=<name>                          → device.id
GET plugins/credentials/devicecredentials/?device=<id> → credential id
GET plugins/credentials/networkcredentials/<id>/       → username + encrypted password
                                                          decrypted locally with the Fernet key

在选择此形态之前需要了解的事项：

• Fernet 密钥是整个安全边界。 它在服务器内存中解密设备密码。需像对待密码本身一样对待它。

• 如果没有 FEDELE_CREDENTIALS_KEY，服务器仍然会启动，但每个工具都会返回相同的 Startup Error，并指出缺少的变量。它会响亮地失败，而非静默。

• 设置范围过滤器。 如果没有 NETMIKO_MCP_FEDELE_DEVICE_FILTER，清单将是 SoT 知道的所有资产，也就是智能体能访问的所有设备。缺失时服务器会记录警告；过滤器支持查询语法，例如 tag=lab&status=active。

• 没有 primary_ip、没有 platform，或平台不是 Netmiko device_type 的设备会被排除在清单之外——SoT 还会记录摄像头、门禁读卡器和机箱。排除项会被计数并报告，因此智能体绝不会在子集上声称“这些是所有设备”。

• 存在一个断路器：在传输错误或 5xx 后，客户端会停止调用 SoT 30 秒。如果 SoT 宕机，对 40 台设备执行组命令只会失败一次，而不是四十次。

B — 清单来自 SoT，凭据来自 .env 文件

与 A 相同，只需切换一个变量：

"NETMIKO_MCP_CREDENTIAL_SOURCE": "env",

# .env
FEDELE_URL=https://sot.example.com
FEDELE_TOKEN=<API token>
NETMIKO_USERNAME=<service account>
NETMIKO_PASSWORD=<password>
NETMIKO_SECRET=<enable password, if any device asks for it>

你可以获得动态清单——这是物有所值的部分——而无需凭据插件和 Fernet 密钥。所有设备使用同一个服务账户。

NetBox，或任何 NetBox 形态的 SoT

清单后端使用 NetBox REST 方言，因此 NetBox 本身在此形态中无需修改即可工作：

将 FEDELE_URL 指向 NetBox 实例（如果未添加 /api，会自动追加），FEDELE_TOKEN 指向 NetBox API 令牌——客户端使用 NetBox 期望的 Authorization: Token … 头进行认证。变量保留 FEDELE_ 前缀；这是命名遗留问题，而非产品要求。

NetBox 默认不满足的一个要求：platform.name 必须恰好是 Netmiko device_type —— cisco_ios、arista_eos、huawei_vrp、juniper_junos。名为 "Cisco IOS 15.2" 的平台不是 device_type，因此注册了该平台的每个设备都会被排除在清单之外。要么在 NetBox 中重命名平台，要么接受排除项——排除项会被报告。

凭据是 NetBox 未涵盖的部分：plugins/credentials/… 端点属于 Fedele 的插件。使用普通 NetBox 时，形态 A 不可用——请停留在形态 B。

C — 自包含：无需 SoT

所有内容都存储在此项目中。永远不会联系外部服务。

// .mcp.json → env
"NETMIKO_MCP_INVENTORY_TYPE": "yaml",
"NETMIKO_MCP_CREDENTIAL_SOURCE": "env",
"NETMIKO_MCP_INVENTORY_FILE": "/abs/path/claude-project/config/netmiko/inventory.yml"

# .env
NETMIKO_USERNAME=<service account>
NETMIKO_PASSWORD=<password>
NETMIKO_SECRET=<enable password, if any device asks for it>

文件：inventory.yml 在这里是必需的——它是设备唯一存在的地方。commands.yml 仍然是推荐的，但不是必需的。清单采用 netmiko_tools 格式——一个将名称映射到连接数据的扁平结构，加上组键：

CORE-RTR-01:
  device_type: cisco_xr        # must be a Netmiko device_type, verbatim
  host: 192.0.2.11

CORE-SW-01:
  device_type: arista_eos
  host: 192.0.2.21

core:                          # a group is a list of device names
- CORE-RTR-01
- CORE-SW-01

该项目附带的文件是示例数据：12 台虚构设备位于 RFC 5737 文档范围内，7 个组，以及选择的平台，使得允许列表中提到的每个 CLI 方言都有代表。请用您自己的设备替换它。

这是该项目配置的默认风格，同时也是降级模式：如果 SoT 宕机，两个变量和一次重启就可以将 flavor-A 或 flavor-B 部署迁移到这里。在需要之前演练一下是值得的。

代价是文件会过时。父仓库中的 scripts/export_inventory.py 会从 SoT 重新生成它；请按计划运行。携带六个月前地址的备份清单比完全没有备份更糟糕，因为您会在操作时才发现问题。

三种风格中保持不变的内容

命令策略、审计跟踪、输出分页和工具界面在三种风格之间不会改变。面向代理的契约是相同的，这就是为什么技能不需要针对每种风格进行变体。

commands.yml 是推荐的，但不是必需的

服务器可以在没有它的情况下运行。如果文件缺失，它不会拒绝所有命令，也不会拒绝启动：一个内置的 16 条只读命令回退会接管——show version、show ip interface brief、display version 及其 Junos/VRP 等效命令。这是有意为之。空策略会拒绝所有命令，而服务器仍然报告自己健康，这会让操作员理解为"设备拒绝"而不是"没有人编写策略"。回退在启动时宣布，netmiko.get_command_policy 报告 policy_source: "fallback"，并且每次审计的尝试都携带来源。

所以该文件是一个策略决策，而不是安装步骤：回退让您可以在第一次尝试时运行服务器，当您想要使用设备自己的策略而不是保守的默认值时，再编写 commands.yml。您不能做的是拥有一个您没有选择且不知道的策略——服务器每次被询问时都会说明哪个策略正在生效。

.mcp.json 文件

项目根目录下的 .mcp.json 声明了此项目的 MCP 服务器。Claude Code 在第一次看到该文件时请求批准，并且该文件应该被提交：这是整个团队获得相同服务器的方式。

同一服务器定义还存在另外两个作用域：

claude mcp add --scope project netmiko -- /path/to/python /path/to/server.py 会为您写入 project 条目；手动编辑 JSON 是等效的。

文件结构

{
  "mcpServers": {           // ← the top-level key. Not "servers", not "mcp".
    "netmiko": {            // ← the server name; it becomes the tool prefix
      ...                   //    mcp__netmiko__<tool>
    }
  }
}

服务器名称不是装饰性的：Claude Code 将每个工具暴露为 mcp__<server-name>__<tool-name>。使用名称 netmiko 和服务器注册的工具 netmiko.get_metadata，Claude 实际看到的工具是 mcp__netmiko__netmiko.get_metadata。运行 /mcp 读取确切的名称，然后再将它们写入 allowed-tools 列表或权限规则中。

字段参考

值支持环境变量扩展：${VAR} 和 ${VAR:-default}。对于将令牌保留在已提交文件之外很有用：

"headers": { "Authorization": "Bearer ${NETMIKO_MCP_TOKEN}" }

传输方式 1 — stdio（本项目使用的）

Claude Code 将服务器作为子进程生成，并通过其 stdin/stdout 进行 JSON-RPC 通信。没有端口在监听，没有东西可以从网络访问，进程生命周期与会话相同。对于持有 SSH 凭据的服务器来说，这是正确的默认设置。

{
  "mcpServers": {
    "netmiko": {
      "type": "stdio",
      "command": "${CLAUDE_PROJECT_DIR:-.}/.venv/bin/python",
      "args": ["${CLAUDE_PROJECT_DIR:-.}/mcps/mcp_server_netmiko.py"],
      "env": {
        "NETMIKO_MCP_INVENTORY_TYPE": "yaml",
        "NETMIKO_MCP_INVENTORY_FILE": "${CLAUDE_PROJECT_DIR:-.}/config/netmiko/inventory.yml",
        "NETMIKO_MCP_COMMAND_FILE": "${CLAUDE_PROJECT_DIR:-.}/config/netmiko/commands.yml",
        "NETMIKO_MCP_CREDENTIAL_SOURCE": "env",
        "NETMIKO_MCP_SAVE_OUTPUT_DIR": "${CLAUDE_PROJECT_DIR:-.}/mcpr/netmiko",
        "NETMIKO_MCP_AUDIT_LOG_FILE": "${CLAUDE_PROJECT_DIR:-.}/logs/netmiko-audit.jsonl",
        "LOG_FILE": "${CLAUDE_PROJECT_DIR:-.}/logs/netmiko-mcp.log",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

两件需要注意的事情：

• 没有硬编码路径，工作目录不可依赖。${CLAUDE_PROJECT_DIR:-.} 是保持文件可原样提交的关键；下一节是完整的故事，因为对其的直观理解是错误的。

• 服务器不得写入 stdout。 stdout 就是协议通道，任何一行杂散输出都会破坏会话。日志记录转到 stderr 加上 LOG_FILE 的轮转文件（5 MB × 3，创建时权限为 0600——在 DEBUG 级别，此文件携带设备输出）。在 Niko 内部，相同的变量由 MCPLogging 处理。

${CLAUDE_PROJECT_DIR:-.} 的来源

一个字符串中的两个独立事物：一个语法和一个变量。

语法。 ${VAR} 和 ${VAR:-default} 是 POSIX 参数替换（"使用 VAR；如果未设置或为空，则使用 default"），但不涉及 shell——JSON 文件永远不会经过 shell。Claude Code 在读取文件时自行实现扩展，适用于 command、args、env、url 和 headers。这是该客户端的约定，不是 MCP 规范的一部分：另一个客户端可能不实现它（参见 非 Claude 代理，那里的路径必须是字面量），而 VS Code 有自己的写法 ${workspaceFolder}。

变量。 CLAUDE_PROJECT_DIR 由 Claude Code 设置为项目根目录，与钩子接收的值相同。它是稳定的——在会话中间使用 --add-dir 授予额外的工作目录不会改变它。

违反直觉的部分，也是 :-. 不是装饰的原因：Claude Code 将该变量设置在它生成的服务器环境中，而不是它自己的环境中。然而，扩展发生在生成之前，针对的是 Claude Code 的环境——该变量在那里不存在。因此，裸的 ${CLAUDE_PROJECT_DIR} 会扩展为空，留下 /config/netmiko/inventory.yml，一个指向文件系统根目录的绝对路径。

所以在项目范围的 .mcp.json 中，默认值不是某些边缘情况的回退：它是每次使用的值。 到达进程的是 ./config/netmiko/inventory.yml。唯一的例外是由插件提供的 MCP 配置——在那里 Claude Code 直接替换变量，不需要默认值。

这就是迫使服务器做出决定的原因。相对值会相对于子进程的工作目录解析，而工作目录是客户端的选择，不是项目的选择。因此有了 resolve_project_path()：每个相对路径设置在加载时都锚定到 PARENT_DIR——mcps/ 的父目录，与 .env 来自的同一个根目录。从任何地方启动的会话都能找到 config/netmiko/，并且 validate_startup() 在文件缺失时命名绝对文件。~ 仍然表示操作员的主目录，永远不会是项目内的文件。

该变量仍然按照文档的意图有用，从服务器内部读取（os.environ["CLAUDE_PROJECT_DIR"]），在那里它被设置。此服务器不需要它：PARENT_DIR 从 __file__ 派生，因此完全不依赖于任何客户端——同样的原因，HTTP 传输（没有人设置该变量）不需要特殊情况。

来源：Claude Code — MCP，添加本地 stdio 服务器和*.mcp.json 中的环境变量扩展*部分。

传输方式 2 — HTTP（可流式 HTTP）

Claude Code 支持它，任何其他 MCP 客户端也支持。当服务器在其他地方运行时使用此传输方式：另一台主机、容器、多个代理共享的服务，或者不是 Claude 的代理。

服务器文件总是在其 __main__ 保护下调用 mcp.run(transport="stdio")，因此 HTTP 改为由 FastMCP CLI 提供——无需更改代码：

.venv/bin/fastmcp run mcps/mcp_server_netmiko.py \
  --transport http --host 127.0.0.1 --port 8123
# endpoint: http://127.0.0.1:8123/mcp/

NETMIKO_MCP_* 变量不再是客户端配置的一部分：服务器进程由您启动，因此它们属于它的环境（shell 导出、systemd 单元、容器的 environment: 块）。

客户端：

{
  "mcpServers": {
    "netmiko": {
      "type": "http",
      "url": "http://127.0.0.1:8123/mcp/",
      "headers": {
        "Authorization": "Bearer ${NETMIKO_MCP_TOKEN}"
      }
    }
  }
}

或者等效地，claude mcp add --transport http netmiko http://127.0.0.1:8123/mcp/。

--transport sse 和 "type": "sse" 也有效；SSE 是较旧的远程传输方式，为尚未迁移到可流式 HTTP 的客户端保留。

安全。 FastMCP CLI 在没有身份验证的情况下提供此服务：任何能访问端口的人都可以对清单中的每台设备运行 show 命令，使用服务器环境中的凭据。对于本地测试绑定到 127.0.0.1，对于任何共享的内容，将其放在终止 TLS 并检查 Authorization 头的反向代理后面。上面的 headers 块是客户端发送的内容；代理是必须验证它的东西。

非 Claude 代理

这里展示的 mcpServers 对象是事实上的结构：Claude Code、Claude Desktop、Cursor 和 Windsurf 都读取相同的三个 stdio 字段（command / args / env）和相同的两个远程字段（url / headers）。在它们之间复制条目通常可以直接工作。

在复制之前值得检查的已知差异：

• VS Code 使用 mcp.json，顶层键是 "servers" 而不是 "mcpServers"，并且它要求显式声明 "type"。

• 某些客户端不实现 ${VAR} 扩展；在那里值必须是字面量，这是使用 HTTP 传输加代理而不是将令牌粘贴到已提交文件中的论据。

• 根本没有配置文件的代理仍然可以直接与 HTTP 端点通信——URL 和 Authorization 头就是整个契约。

env 块

NETMIKO_MCP_* 条目优先于任何 YAML 配置文件。它们被显式设置，因为在 Niko 之外没有 NikoPaths，所以默认值回退到 ~/commands.yml 和 ~/.netmiko_mcp_tmp。

这里的每个路径都可以相对于项目根目录编写：服务器在设置加载时将相对值锚定到 PARENT_DIR，因此生成的进程的工作目录永远不会决定清单或审计跟踪的位置。绝对路径或 ~ 按原样使用。

凭证不在此设置。NETMIKO_USERNAME、NETMIKO_PASSWORD、 NETMIKO_SECRET 以及 FEDELE_* 变量从 <项目根目录>/.env 读取，确保它们不会出现在已提交的 JSON 文件中。 优先级：env 块中的内容会静默覆盖 .env 中的内容——请确保每个变量只在一个位置定义。

其他所有变量均在父级仓库的 README 中有文档说明。

验证是否正常工作

claude mcp list          # netmiko: ✓ connected

在会话中，/mcp 列出工具，/skills 确认技能已加载。询问当前生效的策略，netmiko.get_command_policy 会返回正在读取的文件名——或报告 "fallback"，表示从未找到该文件，正在使用 16 条内置命令运行。

作者：Ed Scrimaglia edgardo.scrimaglia@gmail.com — 最后更新：2026-08-18.