NetBrain MCP

# NetBrain MCP 用户操作指南 本文档是NetBrain MCP系统的完整用户操作指南，将指导您从安装配置到高级功能使用的全过程。 ## 1. 项目简介 ### 1.1 什么是NetBrain MCP？ NetBrain MCP（Model Context Protocol）是一个开源的网络运维整合平台，通过MCP协议连接大型语言模型（LLM）与网络设备。它允许AI助手通过标准化协议执行网络配置、诊断和管理任务。 ### 1.2 核心功能 #### 🔧 设备管理功能 - **统一设备管理**：支持思科、华为、H3C、Juniper等主流厂商设备 - **多协议连接**：支持SSH、Telnet、SNMP等连接协议 - **凭据安全管理**：加密存储设备访问凭据 - **设备状态监控**：实时监控设备连接状态 #### 🌐 网络操作功能 - **命令执行**：远程执行网络设备命令 - **配置管理**：设备配置备份、比较和部署 - **拓扑发现**：基于CDP/LLDP的自动拓扑发现 - **网络扫描**：网络范围扫描和设备识别 #### 🤖 AI集成功能 - **32个MCP工具**：涵盖设备管理、连接控制、拓扑分析等 - **13个MCP资源**：提供设备信息、配置数据、拓扑数据等 - **13个提示模板**：专业的网络诊断和配置模板 - **智能诊断**：AI驱动的网络问题分析和解决方案 #### 💻 Web界面功能 - **专业终端**：基于XTerm.js的多标签页终端体验 - **拓扑可视化**：基于D3.js的交互式网络拓扑图 - **设备管理界面**：直观的设备添加、编辑和监控界面 - **主题系统**：支持暗色/明亮主题切换 ## 2. 系统要求 ### 2.1 硬件要求 - **CPU**：2核心以上 - **内存**：4GB以上 - **存储**：10GB可用空间 - **网络**：能够访问目标网络设备 ### 2.2 软件要求 - **操作系统**：Windows 10+、Linux、macOS - **Python版本**：Python 3.10或更高版本 - **网络访问**：SSH/Telnet访问目标设备的权限 ### 2.3 支持的设备 - **思科设备**：IOS、IOS-XE、NX-OS - **华为设备**：VRP系统 - **H3C设备**：Comware系统 - **Juniper设备**：JUNOS系统 - **其他厂商**：支持标准SSH/Telnet协议的设备 ## 3. 安装和配置 ### 3.1 获取项目代码 ```bash # 克隆项目（假设从Git仓库） git clone https://github.com/your-org/NetBrainMCP.git cd NetBrainMCP # 或者下载项目压缩包并解压 # wget https://github.com/your-org/NetBrainMCP/archive/main.zip # unzip main.zip # cd NetBrainMCP-main ``` ### 3.2 创建Python虚拟环境 ```bash # 创建虚拟环境 python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # Linux/macOS: source venv/bin/activate ``` ### 3.3 安装依赖 ```bash # 安装项目依赖 pip install -r requirements.txt # 验证关键依赖安装 python -c "import scrapli; print('Scrapli版本:', scrapli.__version__)" python -c "import mcp; print('MCP已安装')" ``` ### 3.4 配置环境变量（可选） ```bash # 设置日志级别 export LOG_LEVEL=INFO # 设置数据目录 export DATA_DIR=./data # 设置加密密钥（用于凭据加密） export ENCRYPTION_KEY=your-secret-key ``` ## 4. 快速开始 ### 4.1 启动MCP服务器 ```bash # 启动MCP服务器（标准输入输出模式） python server.py # 或启动Web服务器模式 python server.py --web ``` ### 4.2 连接到Claude Desktop 1. **安装Claude Desktop** - 从 https://claude.ai/download 下载并安装Claude Desktop 2. **配置MCP服务器** 编辑Claude Desktop配置文件： - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` 添加配置： ```json { "mcpServers": { "netbrain-mcp": { "command": "python", "args": ["/path/to/NetBrainMCP/server.py"], "env": { "LOG_LEVEL": "INFO" } } } } ``` 3. **重启Claude Desktop** - 重启Claude Desktop，您将看到工具图标，表示MCP服务器已连接 ### 4.3 连接到Cursor IDE 1. **启动SSE模式** ```bash python server.py --mode sse --port 8000 ``` 2. **配置Cursor** - 打开Cursor → 设置 → 功能 → MCP服务器 - 添加新服务器： - **名称**: netbrain-mcp - **类型**: sse - **URL**: http://localhost:8000/sse ## 5. 基本操作指南 ### 5.1 设备管理 #### 添加设备凭据 首先添加设备访问凭据： ``` # 在Claude或Cursor中输入： 请帮我添加一个思科设备的SSH凭据，用户名是admin，密码是cisco123 ``` AI将调用`add_credential`工具： - 用户名：admin - 密码：cisco123 - 协议：ssh - 端口：22 #### 添加网络设备 ``` # 添加思科路由器 请添加一台思科路由器，名称是Router-01，IP地址是192.168.1.1，使用刚才添加的凭据 ``` AI将调用`add_device`工具添加设备。 #### 查看设备列表 ``` 显示所有网络设备的列表 ``` AI将调用`list_devices`工具显示所有已添加的设备。 ### 5.2 设备连接和命令执行 #### 连接到设备 ``` 请连接到Router-01设备 ``` AI将调用`connect_device`工具建立与设备的连接。 #### 执行命令 ``` # 查看设备版本信息 在Router-01上执行 show version 命令 # 查看接口状态 在Router-01上执行 show ip interface brief 命令 # 执行多个命令 在Router-01上依次执行以下命令： 1. show running-config 2. show ip route 3. show interface status ``` AI将调用`send_command`或`send_commands`工具执行相应命令。 ### 5.3 网络拓扑发现 #### 发现设备拓扑 ``` 请发现Router-01的网络拓扑 ``` AI将调用`discover_topology`工具，通过CDP/LLDP协议发现网络拓扑。 #### 查看拓扑信息 ``` 显示当前网络拓扑的统计信息 ``` AI将调用`get_topology_statistics`工具显示拓扑统计。 ### 5.4 网络扫描 #### 扫描网络范围 ``` 请扫描192.168.1.0/24网段，发现网络设备 ``` AI将调用`scan_network_range`工具进行网络扫描。 #### 查看扫描结果 ``` 显示网络扫描的结果 ``` AI将调用`get_scan_results`工具显示扫描发现的设备。 ## 6. 高级功能 ### 6.1 使用提示模板 #### 设备诊断模板 ``` 使用设备诊断模板分析Router-01的状态 ``` AI将使用`device_diagnosis`模板，结合设备信息和接口状态进行专业分析。 #### 配置审查模板 ``` 使用配置审查模板检查Router-01的配置 ``` AI将使用`config_review`模板对设备配置进行安全和最佳实践审查。 #### 网络故障排除模板 ``` 使用故障排除模板分析网络连接问题 ``` AI将使用`network_troubleshooting`模板进行系统化的故障排除。 ### 6.2 使用MCP资源 #### 访问设备信息资源 ``` 获取device://router-01的设备信息资源 ``` #### 访问配置资源 ``` 获取device://router-01/config的配置资源 ``` #### 访问拓扑资源 ``` 获取topology://的网络拓扑资源 ``` ### 6.3 Web界面使用 #### 启动Web界面 ```bash python server.py --web --port 8080 ``` 然后在浏览器中访问：http://localhost:8080 #### Web界面功能 1. **设备管理页面** - 添加、编辑、删除设备 - 管理设备凭据 - 查看设备状态 2. **终端页面** - 多标签页终端 - 实时命令执行 - 命令历史和补全 3. **拓扑页面** - 交互式拓扑图 - 拓扑发现控制 - 设备详情查看 ## 7. 配置管理 ### 7.1 数据存储配置 系统数据存储在以下位置： ``` NetBrainMCP/ ├── data/ │ ├── devices.json # 设备信息 │ └── credentials.json # 凭据信息（加密存储） ├── resource_cache/ # 资源缓存 └── templates/ # 模板缓存 ``` ### 7.2 日志配置 日志文件位置： ``` NetBrainMCP/ └── logs/ ├── netbrain_mcp.log # 主日志 ├── device_connector.log # 连接日志 └── audit.log # 审计日志 ``` ### 7.3 缓存配置 - **资源缓存**：默认5分钟TTL - **设备配置缓存**：默认10分钟TTL - **拓扑缓存**：默认15分钟TTL 可在代码中调整缓存设置： ```python # 在mcp_resources.py中 self.default_cache_ttl = 300 # 5分钟 ``` ## 8. 故障排除 ### 8.1 常见问题 #### 连接问题 **问题**：无法连接到设备 ``` 解决方案： 1. 检查设备IP地址是否正确 2. 验证网络连通性（ping测试） 3. 确认SSH/Telnet服务已启用 4. 检查凭据是否正确 5. 查看防火墙设置 ``` **问题**：连接超时 ``` 解决方案： 1. 增加连接超时时间 2. 检查网络延迟 3. 确认设备负载不高 4. 检查并发连接限制 ``` #### MCP服务器问题 **问题**：Claude Desktop无法连接MCP服务器 ``` 解决方案： 1. 检查配置文件路径是否正确 2. 验证Python路径和脚本路径 3. 检查权限设置 4. 查看Claude Desktop日志 5. 重启Claude Desktop ``` **问题**：工具调用失败 ``` 解决方案： 1. 检查Python环境和依赖 2. 查看MCP服务器日志 3. 验证工具参数格式 4. 检查设备连接状态 ``` ### 8.2 调试技巧 #### 启用详细日志 ```bash # 设置日志级别为DEBUG export LOG_LEVEL=DEBUG python server.py ``` #### 查看实时日志 ```bash # Linux/macOS tail -f logs/netbrain_mcp.log # Windows (PowerShell) Get-Content logs/netbrain_mcp.log -Wait ``` #### 测试设备连接 ```python # 使用test_scrapli_connection工具 python -c " import asyncio from server import test_scrapli_connection result = asyncio.run(test_scrapli_connection( host='192.168.1.1', username='admin', password='cisco123', platform='cisco_iosxe' )) print(result) " ``` ### 8.3 性能优化 #### 连接池配置 ```python # 在device_connector.py中调整连接池大小 MAX_CONNECTIONS = 10 # 最大并发连接数 CONNECTION_TIMEOUT = 30 # 连接超时时间 ``` #### 缓存优化 ```python # 调整缓存策略 RESOURCE_CACHE_TTL = 300 # 资源缓存时间 CONFIG_CACHE_TTL = 600 # 配置缓存时间 TOPOLOGY_CACHE_TTL = 900 # 拓扑缓存时间 ``` ## 9. 最佳实践 ### 9.1 设备管理最佳实践 1. **统一命名规范** ``` 设备命名：<位置>-<类型>-<编号> 示例：DC1-RTR-01、DC1-SW-02 ``` 2. **标签使用** ``` 按功能分类：core, access, distribution 按环境分类：production, staging, development 按位置分类：datacenter1, branch-office, remote ``` 3. **凭据管理** ``` - 为不同设备类型创建专用凭据 - 定期轮换密码 - 使用SSH密钥认证（推荐） - 设置不同权限级别的凭据 ``` ### 9.2 安全最佳实践 1. **网络安全** ``` - 限制MCP服务器的网络访问 - 使用VPN或专用网络连接 - 启用设备访问日志记录 - 定期审查访问权限 ``` 2. **数据保护** ``` - 定期备份设备和凭据数据 - 使用强密码和加密 - 限制文件系统访问权限 - 监控异常访问活动 ``` ### 9.3 运维最佳实践 1. **监控和告警** ``` - 监控MCP服务器状态 - 设置设备连接告警 - 记录重要操作日志 - 定期检查系统资源使用 ``` 2. **维护计划** ``` - 定期更新依赖包 - 清理过期缓存文件 - 归档旧日志文件 - 验证备份数据完整性 ``` ## 10. API参考 ### 10.1 MCP工具列表 #### 设备管理工具 - `list_devices` - 列出设备 - `add_device` - 添加设备 - `get_device` - 获取设备信息 - `update_device` - 更新设备 - `delete_device` - 删除设备 #### 连接管理工具 - `connect_device` - 连接设备 - `disconnect_device` - 断开连接 - `send_command` - 发送命令 - `send_commands` - 发送多个命令 - `get_active_connections` - 获取活动连接 #### 拓扑发现工具 - `discover_topology` - 发现拓扑 - `get_topology` - 获取拓扑 - `clear_topology` - 清除拓扑 - `get_device_neighbors` - 获取邻居 - `get_topology_statistics` - 拓扑统计 ### 10.2 MCP资源列表 #### 设备资源 - `device/{device_id}` - 设备基本信息 - `device/{device_id}/config` - 设备配置 - `device/{device_id}/interfaces` - 接口信息 - `device/{device_id}/routes` - 路由信息 - `device/{device_id}/neighbors` - 邻居信息 #### 系统资源 - `credentials` - 凭据列表 - `system/status` - 系统状态 - `topology` - 网络拓扑 - `scan/results` - 扫描结果 ### 10.3 提示模板列表 #### 诊断模板 - `device_diagnosis` - 设备诊断 - `network_troubleshooting` - 网络故障排除 - `performance_optimization` - 性能优化 #### 配置模板 - `config_review` - 配置审查 - `security_audit` - 安全审计 - `vlan_config` - VLAN配置 ## 11. 扩展开发 ### 11.1 添加新的MCP工具 ```python @mcp.tool() async def custom_tool(param1: str, param2: int) -> Dict[str, Any]: """自定义工具描述""" # 工具实现逻辑 return {"result": "success"} ``` ### 11.2 添加新的MCP资源 ```python @resource_manager.register_resource("custom/{id}", ResourceType.CUSTOM) async def get_custom_resource(id: str) -> Dict[str, Any]: """自定义资源描述""" # 资源获取逻辑 return {"data": "custom_data"} ``` ### 11.3 添加新的提示模板 ```python @template_manager.register_template( name="custom_template", description="自定义模板描述" ) def custom_template(param1: str, param2: str) -> str: """自定义模板实现""" return f"自定义提示：{param1} - {param2}" ``` ## 12. 社区和支持 ### 12.1 获取帮助 - **文档**：查看完整的技术文档 - **示例**：参考examples目录中的使用示例 - **FAQ**：查看常见问题解答 ### 12.2 贡献代码 欢迎为NetBrain MCP项目贡献代码： 1. Fork项目仓库 2. 创建功能分支 3. 提交代码变更 4. 创建Pull Request ### 12.3 报告问题 如发现bug或有功能建议，请： 1. 检查已知问题列表 2. 提供详细的错误信息 3. 包含复现步骤 4. 提交Issue或联系维护团队 --- 通过本指南，您应该能够熟练使用NetBrain MCP系统进行网络设备管理和AI驱动的网络运维工作。如有任何问题，请参考故障排除部分或联系技术支持团队。