使用说明

NetContext MCP-通过模型上下文协议实现网络设备自动化

人工智能驱动的网络自动化 通过基于SSH的网络设备管理的模型上下文协议。

什么是NetContext MCP？

NetContext提供了一个MCP服务器，使AI助手（Claude Desktop、LM Studio等）能够通过SSH在网络设备上执行命令。通过您最喜欢的人工智能工具，使用自然语言控制您的网络基础设施。

特性

✅ 生产就绪SSH支持：使用真实设备（Aruba交换机、UniFi路由器）进行测试
🔐 多种身份验证方法：密码、键盘交互、SSH密钥、SSH代理
🏗️ 协议抽象：支持传统和现代SSH实现的干净架构
📟 设备分页处理：自动检测和处理CLI分页提示
🛡️ 安全第一：命令清理、凭据保护、超时管理
⚡ 批量操作：在多个设备上并行执行命令
🐳 Docker测试环境：用于开发的预配置SSH测试服务器

支持的设备

供应商	型号	身份验证	状态
思科	IOS/IOS-XE（催化剂/ISR/ASR）	密码/按键/键盘输入	✅ 生产
惠普/阿鲁巴	ProCurve开关（2530/2920）	密码	✅ 生产
优比快	UniFi Dream Router	键盘互动	✅ 生产
通用的	Linux/SSH服务器	密码/密钥	✅ 支持

关键能力:

多供应商支持：思科、惠普/阿鲁巴岛、Ubiquiti和通用SSH设备
传统SSH支持：适用于较旧的网络设备（diffie-hellman-group14-sha1，ssh-rsa）
现代SSH支持：完全支持当前算法（curve25519-sha256、chacha20-poly1305）
设备特定处理：分页、提示检测、特定于供应商的命令
错误检测：思科特有的错误模式识别和报告

快速开始

1.安装

# Clone repository
git clone https://github.com/hgursel/NetContext-MCP.git
cd NetContext-MCP

# Install dependencies
npm install

# Build the MCP server
npm run build

2.使用Claude Desktop进行设置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或同等版本：

{
  "mcpServers": {
    "netcontext-network": {
      "command": "node",
      "args": [
        "/path/to/NetContext-MCP/packages/network-mcp/dist/index.js"
      ],
      "env": {
        "DEVICE_USERNAME": "admin",
        "DEVICE_PASSWORD": "your-default-password",
        "SSH_TIMEOUT": "10000",
        "DEFAULT_PROTOCOL": "ssh"
      }
    }
  }
}

重要:

替换 /path/to/NetContext-MCP 使用您的实际安装路径
每个命令都可以覆盖默认凭据
对于生产，使用SSH密钥而不是密码（请参阅安全)

3.使用LM Studio进行设置

LM Studio通过配置支持MCP服务器。添加到LM Studio MCP配置中：

{
  "mcpServers": {
    "netcontext": {
      "command": "node",
      "args": ["/path/to/NetContext-MCP/packages/network-mcp/dist/index.js"],
      "env": {
        "DEVICE_USERNAME": "admin",
        "SSH_TIMEOUT": "10000"
      }
    }
  }
}

4.重新启动AI客户端

克劳德桌面：退出（Cmd+Q）并重新启动
LM工作室：重新启动应用程序
其他MCP客户端：遵循他们的重启程序

5.测试连接

在您的AI助手中，尝试：

Execute "show version" on my Aruba switch at 192.168.1.10 with username manager and password mypassword

或

Run "uname -a" on UniFi router at 10.10.21.1 with username root and password mypassword

使用示例

Aruba ProCurve交换机

Show version information on the Aruba switch at 192.168.2.217 with credentials manager/password

发生了什么:

MCP服务器通过SSH连接（自动处理传统算法）
检测CLI提示并禁用分页
执行 show version 命令
返回设备型号、软件版本、序列号

示例输出:

HP J9729A 2920-48G-POE+ Switch
Software revision WB.16.02.0012
Serial Number: CNXXXXXXXX

思科IOS/IOS-XE路由器或交换机

Get device information from Cisco router at 192.168.1.1 with credentials admin/cisco123

发生了什么:

MCP服务器通过SSH连接（支持密码、键盘交互或SSH密钥）
自动发送 terminal length 0 禁用分页
执行 show version 命令
如果命令失败，则检测Cisco错误模式

示例输出:

Cisco IOS Software, C2960X Software (C2960X-UNIVERSALK9-M), Version 15.2(7)E8
Technical Support: http://www.cisco.com/techsupport
System image file is "flash:c2960x-universalk9-mz.152-7.E8.bin"
uptime is 45 weeks, 2 days, 3 hours, 15 minutes

可用命令包 （in vendor/cisco-ios-iosxe/commands.yml):

health_check -基本系统运行状况（版本、接口、CPU、内存）
security_audit -安全配置审查
interface_troubleshooting -接口诊断
vlan_troubleshooting -VLAN配置和连接（交换机）
routing_troubleshooting -路由表和协议（路由器）

UniFi梦想路由器

Get system information from UniFi router at 10.10.21.1 with username root and password mypassword

发生了什么:

MCP服务器通过SSH连接（使用键盘交互式身份验证）
执行Linux命令： uname -a
返回内核和固件版本

示例输出:

Linux UDR7 5.4.213-ui-ipq5322-wireless #5.4.213 SMP PREEMPT aarch64 GNU/Linux
Firmware version: v4.3.9

批处理执行

Get uptime from these devices in parallel:
- Aruba switch at 192.168.2.217 (manager/password)
- UniFi router at 10.10.21.1 (root/mypassword)

发生了什么:

MCP服务器同时在两个设备上执行命令
返回每个设备状态的组合结果
显示每个设备的执行时间

配置

环境变量

在MCP客户端的配置文件中配置：

变量	描述	默认值
`DEVICE_USERNAME`	默认SSH用户名	`netadmin`
`DEVICE_PASSWORD`	默认SSH密码	`testpass123`
`SSH_TIMEOUT`	连接超时（ms）	`10000`
`DEFAULT_PROTOCOL`	使用协议	`ssh`
`SSH_VERIFY_HOST_KEY`	验证SSH主机密钥	`false`

按命令凭据

您可以在每个命令中覆盖默认凭据：

Execute "show vlan" on 192.168.1.10 with username admin and password secret123

SSH密钥认证

对于生产使用，配置SSH密钥：

{
  "env": {
    "DEVICE_USERNAME": "admin",
    "DEVICE_PRIVATE_KEY": "/home/user/.ssh/network_devices_rsa"
  }
}

建筑

协议抽象层

┌─────────────────────────────────────────┐
│     AI Assistant (Claude/LM Studio)     │
└────────────────┬────────────────────────┘
                 │ MCP Protocol
                 │
┌────────────────▼────────────────────────┐
│       NetContext MCP Server             │
│                                         │
│  Tools:                                 │
│  - execute_commands                     │
│  - batch_execute                        │
│  - execute_bundle                       │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│      Protocol Abstraction Layer         │
│                                         │
│  - SSHProtocol                          │
│  - Credential Management                │
│  - Command Sanitization                 │
│  - Error Handling                       │
└────────────────┬────────────────────────┘
                 │ SSH (various auth methods)
                 │
┌────────────────▼────────────────────────┐
│         Network Devices                 │
│                                         │
│  - Aruba Switches (legacy SSH)          │
│  - UniFi Routers (keyboard-interactive) │
│  - Linux Servers (standard SSH)         │
└─────────────────────────────────────────┘

支持的身份验证方法

密码验证：标准用户名/密码
键盘交互：挑战响应（UniFi、一些Linux系统）
SSH私钥：基于密钥的身份验证
SSH代理：代理转发支持

设备特定功能

Aruba交换机：分页处理（“按任意键继续”）、传统SSH算法、HP ProCurve CLI
UniFi路由器：键盘交互式身份验证、现代SSH算法、标准Linux命令
通用设备：具有全面算法支持的标准SSH

安全最佳实践

凭据管理

❌ 不要 在配置文件中硬编码密码：

{
  "env": {
    "DEVICE_PASSWORD": "admin123"  // Bad!
  }
}

✅ 做 使用SSH密钥：

{
  "env": {
    "DEVICE_USERNAME": "admin",
    "DEVICE_PRIVATE_KEY": "/home/user/.ssh/network_key"
  }
}

✅ 做 使用环境变量：

# In .bashrc or .zshrc
export DEVICE_USERNAME=admin
export DEVICE_PRIVATE_KEY=/home/user/.ssh/network_key

命令消毒

MCP服务器自动阻止危险命令：

✅ 阻碍： rm, del, format, erase, write erase
✅ 块：命令链(&&, ||, ;)
✅ 块：路径遍历(../)
✅ 块：输出重定向(<, >)

网络安全

限制SSH访问：使用ACL限制管理访问
使用跳转主机：不要将设备直接暴露在互联网上
启用日志记录：监视所有SSH会话
轮换凭据：常规密码/密钥轮换
只读帐户：尽可能使用

发展

先决条件

Node.js 18.x或更高版本
npm 9.x或更高版本
TypeScript 5.x

从源代码构建

# Clone repository
git clone https://github.com/hgursel/NetContext-MCP.git
cd NetContext-MCP

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test

Docker测试环境

对于没有真实设备的开发和测试：

# Start test SSH servers
cd docker
docker-compose up -d

# Test connection
ssh -i test-ssh-server/keys/test_key -p 2223 netadmin@localhost 'show version'

# Stop servers
docker-compose down

Docker环境提供：

2台SSH测试服务器（密码认证+密钥认证）
模拟网络设备命令
安全测试环境

故障排除

MCP服务器未加载

症状：AI助手中没有工具

解决方案:

检查配置文件语法（必须是有效的JSON）
验证路径 index.js 绝对正确
完全重启AI客户端
检查日志： ~/Library/Logs/Claude/mcp-server-netcontext-network.log

SSH连接失败

症状: Connection timeout 或 Authentication failed

解决方案:

验证设备是否可访问： ping <IP>
手动测试SSH： ssh user@<IP>
检查凭据是否正确
验证设备上是否启用了SSH
对于Aruba：自动支持传统SSH算法
对于UniFi：自动支持键盘交互式身份验证

命令不返回输出

症状：空输出或超时

解决方案:

增加 SSH_TIMEOUT 在配置中（例如。， 15000)
检查设备CLI提示格式（应检测 # 或 >)
验证特定设备的命令语法
检查分页处理（大多数设备自动）

键盘交互式身份验证失败（UniFi）

解决方案：确保 tryKeyboard: true 已启用（代码中为自动）

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支： git checkout -b feature/new-vendor
添加新功能的测试
提交拉取请求

贡献领域:

其他设备供应商支持
协议实现（HTTP API、NETCONF）
增强的错误处理
文档改进

路线图

电流（v0.1.0）

✅ 具有多种身份验证方法的SSH协议
✅ Aruba ProCurve交换机支持
✅ UniFi Dream路由器支持
✅ Docker测试环境
✅ 指挥净化和安全

计划（v0.2.0）

[]HTTP API协议（适用于基于REST的设备）
[]凭证管理配置文件
[]协议检测系统
[]供应商元数据数据库
[]命令包（健康检查、审计）

未来（v1.0.0）

[]思科IOS/IOS-XE支持
[]Juniper JunOS支持
[]NETCONF协议支持
[]配置备份/还原
[]变更管理工作流程

许可证

GNU通用公共许可证v3.0-请参阅许可证文件以获取详细信息。

致谢

Anthropic：用于模型上下文协议规范
惠普/阿鲁巴：ArubaOS交换机文档
优比快：适用于UniFi操作系统
社区：用于测试和反馈

支持

问题: GitHub问题
讨论: GitHub讨论

使用说明

NetContext MCP-通过模型上下文协议实现网络设备自动化

什么是NetContext MCP？

特性

支持的设备

快速开始

1.安装

2.使用Claude Desktop进行设置

3.使用LM Studio进行设置

4.重新启动AI客户端

5.测试连接

使用示例

Aruba ProCurve交换机

思科IOS/IOS-XE路由器或交换机

UniFi梦想路由器

批处理执行

配置

环境变量

按命令凭据

SSH密钥认证

建筑

协议抽象层

支持的身份验证方法

设备特定功能

安全最佳实践

凭据管理

命令消毒

网络安全

发展

先决条件

从源代码构建

Docker测试环境

故障排除

MCP服务器未加载

SSH连接失败

命令不返回输出

键盘交互式身份验证失败（UniFi）

贡献

路线图

电流（v0.1.0）

计划（v0.2.0）

未来（v1.0.0）

许可证

致谢

支持

相关项目

相关 MCP

网络运维整合平台

网络自动化MCP服务器

远程Shell管理协议

Mist MCP自动化服务器

HPE网络管理统一MCP服务

智能网关架构