claude-project — netmiko MCP server + skill

一个可直接复制的项目，通过 Model Context Protocol 让 AI 代理通过 SSH 对路由器、交换机和防火墙进行只读访问。

它包含两个部分以及它们之间的连接：

• mcps/mcp_server_netmiko.py —— 一个自包含的 MCP 服务器。提供九个工具，每条命令都会根据操作员定义的允许/拒绝列表进行验证，输出通过 ntc-templates 解析为 JSON，并且对每次尝试都有故障关闭的审计追踪。

• .claude/skills/netmiko/SKILL.md —— 这个技能教会代理何时使用这些工具、各平台 CLI 方言是什么样的，以及如何理解拒绝信息。

这里没有任何操作会写入设备。允许列表默认为拒绝——空列表不允许任何操作——并且拒绝侧始终优先于允许侧。

作者与来源

本项目作者为 Ed Scrimaglia — edgardo.scrimaglia@gmail.com，Octupus。服务器、技能、配置模型和文档均为他的作品，专为 Niko 代理编写，并在此打包为独立项目。

它始于一个 fork，且这一来源被公开承认而非隐藏：起点是 Kirk Byers 的工作，而项目已远远超越它。现在这里的成果——基于事实来源的设备清单、凭据解析、三种部署形态、输出分页、审计追踪、技能以及本文档——并非来自上游。

Kirk Byers 的两个上游项目：

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

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

关于 Niko

该服务器是为 Niko 编写的，Niko 是 Ed Scrimaglia 在 Octupus 打造的 Neural Intelligence Knowledge Orchestrator AI 代理。Niko 作为一组 MCP 服务器的前端——事实来源服务器、本服务器、Jira、发送邮件、创建文件等——这样操作员可以用自然语言提问，并从实际环境中获得答案：SoT 回答应该为真的内容，设备本身回答实际为真的内容。

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

• 服务器通过回环（loopback）上的 HTTP 运行，每个服务器一个端口，在 mcps/mcp_config.json 中以 url / transport / local / env 声明——即下文所述的双轴配置，以 Niko 自己的格式表达。

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

这些集成中的每一个都是带有回退的可选导入，因此永远不需要安装 niko。共有四个，下面列出每个导入失败时的降级情况：

在 Niko 之外，没有任何重要的东西会丢失：并发处理器解决的是多进程写同一文件的问题，而这个问题在这里不会出现；列表预算（list budget）则为有自己上下文记账的代理裁剪过长负载。一个文件，两个归宿，没有 fork。

Fedele 是 Niko 的事实来源，这就是为什么 SoT 变量即使指向 NetBox 实例也带有 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 列出 9 个工具，/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 会被忽略——enable 密码也来自 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（事实源）宕机，只需两个变量和一次重启即可将风格A或风格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。在将确切名称写入allowed-tools列表或权限规则之前，请运行/mcp读取它们。

字段参考

值支持环境变量扩展：${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.