MCP Network

MCP网络测试服务器

一个全面、安全的MCP（模型上下文协议）服务器，用于远程网络测试，具有内置的身份验证、确认和防越狱护栏。

⚠️ 人工智能辅助开发通知： 该项目的部分内容是在人工智能工具的帮助下创建的，具有人在环（HITL）监督和基于人的测试。尽管采取了这些措施，人工智能生成的输出仍可能包含错误。强烈建议用户根据自己的用例审查、验证和测试软件。本项目按“原样”提供，不提供任何形式的保证。

动机

此MCP服务器旨在弥合使用AI代理（Claude Code、Codex、Gemini、Warp、OpenCode等）进行服务器配置任务时的关键差距。虽然这些代理擅长为SMTP服务器、web服务器、具有复杂路由的VPN和类似的基础设施任务生成配置脚本，但它们传统上缺乏验证其配置是否实际工作的能力。

例如，代理可能会生成防火墙规则来打开特定端口或配置SSL证书，但它无法验证端口是否实际可访问，或者证书是否正确安装和受信任。通过在最小的云实例上部署这个轻量级的MCP服务器，代理现在可以执行真实世界的网络验证测试，使他们能够根据实际结果而不是假设迭代和自我纠正配置。

� 快速开始

在3分钟内起床并跑步：

步骤1：安装

# Install globally (recommended)
npm install -g @gtrevize/mcp-network

# OR clone from source
git clone https://github.com/gtrevize/mcp-network.git
cd mcp-network
npm install
npm run build

第二步：首次设置

运行交互式安装程序以配置您的环境：

# Global install:
mcp-network-setup

# Source install:
npm run build
bash scripts/setup.sh

这将：

• 生成安全身份验证凭据
• 创建管理员AUTH_TOKEN
• 配置环境文件(~/.mcp-network.env 对于全局安装， .env 来源）
• 提供启动说明

步骤3：启动服务器

# Global install - load environment then start server
export $(cat ~/.mcp-network.env | xargs)
mcp-network-both  # Starts both MCP and REST API servers

# OR start only what you need:
# mcp-network-server  # MCP server only
# mcp-network-api     # REST API server only

# Source install:
npm run start:both  # Starts both servers
# npm start          # MCP server only
# npm run api        # REST API server only

服务器现在正在运行！您将看到：

• MCP服务器：已为MCP客户端准备好stdio传输
• REST API服务器：继续运行http://localhost:3001（Swagger文档位于/api-docs）

第四步：使用客户端

使用交互式CLI客户端测试您的设置：

# Global install:
mcp-network-cli

# Source install:
npm run client

就是这样！ 您现在拥有一个功能齐全的网络测试环境。非常适合：

• 使用AI代理测试服务器配置
• 学习可用的网络工具
• 在部署到生产环境之前验证连接
• 网络诊断实验

生产部署

对于生产环境，您需要将服务器作为守护进程运行：

看 docs/DAEMON.md 有关以下内容的全面指南：

• PM2流程管理器（推荐，跨平台）
• systemd（Linux）
• launchd（macOS）
• Docker（所有平台）

有关AWS、DigitalOcean等的云部署，请参阅 部署 部分。

� 本地部署与云部署

根据您的需求选择正确的部署方法：

• 系统工具： ping, traceroute, dig, whois, nmap, tcpdump, iperf3

再进行

npm install

构建

npm run build

配置

环境变量

复制 .env.example 到 .env 并配置：

cp .env.example .env

所需变量：

• AUTH_TOKEN -带有用户身份和角色的身份验证令牌（请参阅下面的“生成身份验证令牌”）

高级变量（由mcp网络设置自动处理）：

• JWT_SECRET -令牌签名的内部秘密（自动生成）

可选变量：

• LOG_LEVEL -日志记录级别（默认值：info）
• NODE_ENV -环境（开发/生产）
• ACCESS_LOG_FILE -访问日志文件的路径
• LETSENCRYPT_PRODUCTION -使用生产Let's Encrypt（默认值：false）

生成身份验证令牌

服务器使用带有嵌入式用户身份和角色的JWT令牌。生成令牌：

# Global install:
mcp-network-generate-token  
# Example: mcp-network-generate-token admin admin

# Source install:
npm run build
npm run config generate-token
# Or directly: npm run generate-token  

在您的环境中设置生成的令牌：

export AUTH_TOKEN="your-generated-token"

基于角色的访问控制

可用角色：

• 管理员 -完全访问所有工具
• 网络工程师 -访问大多数网络测试工具
• 开发者 -访问基本网络和API测试工具
• 审计员 -只读网络分析工具
• 只读 -最小只读访问

权限

每个工具都需要特定的权限：

• network:api_test -API测试
• network:dns -DNS解析
• network:ip_address -IP检测
• network:ip_geolocation -IP地理定位
• network:iperf -带宽测试
• network:letsencrypt -证书管理
• network:ping -Ping工具
• network:port_scan -端口扫描（nmap）
• network:port_test -端口测试
• network:reverse_dns -反向DNS（PTR记录）
• network:tcpdump -数据包捕获
• network:tls_test -TLS/SSL测试
• network:traceroute -追踪路线工具
• network:whois -WHOIS查询

用法

运行服务器

该项目提供了三种服务器模式和两种安装方法：

选项1：独立命令（全局安装）

在全球范围内安装后 npm install -g @gtrevize/mcp-network:

仅限MCP服务器 （适用于Claude Desktop和MCP客户）：

mcp-network-server

仅限REST API服务器 （用于HTTP/HTTPS访问）：

mcp-network-api

两台服务器同时运行 （建议完全访问）：

mcp-network-both

选项2:npm脚本（源代码安装）

从源目录运行时：

仅限MCP服务器:

# Production
npm start

# Development with auto-reload
npm run dev

仅限REST API服务器:

# Production
npm run api

# Development with auto-reload
npm run dev:api

两台服务器同时运行:

# Production - runs both MCP and REST API servers
npm run start:both

# Development - runs both with auto-reload
npm run dev:both

备注：双服务器模式并行运行两台服务器：

• MCP服务器：MCP协议客户端的stdio传输
• REST API服务器: http://localhost:3001（或已配置的API_PORT）

MCP客户端配置

添加到您的MCP客户端配置中（例如，Claude Desktop）：

先决条件：运行 mcp-network-setup 首先生成您的 ~/.mcp-network.env 使用AUTH_TOKEN文件。

选项1：全局安装（推荐）

{
  "mcpServers": {
    "network": {
      "command": "sh",
      "args": ["-c", "export $(cat ~/.mcp-network.env | xargs) && mcp-network-server"]
    }
  }
}

选项2：手动配置（高级）

如果您不希望从.env文件加载：

{
  "mcpServers": {
    "network": {
      "command": "mcp-network-server",
      "env": {
        "AUTH_TOKEN": "your-auth-token-from-setup",
        "JWT_SECRET": "your-secret-from-env-file"
      }
    }
  }
}

注：这两个值都是由 mcp-network-setup 并存储在 ~/.mcp-network.env.

选项3：源代码安装

{
  "mcpServers": {
    "network": {
      "command": "sh",
      "args": ["-c", "export $(cat /path/to/mcp-network/.env | xargs) && node /path/to/mcp-network/dist/index.js"]
    }
  }
}

工具调用示例

拼

{
  "name": "ping",
  "arguments": {
    "target": "example.com",
    "count": 4
  }
}

端口扫描器

{
  "name": "port_scan",
  "arguments": {
    "target": "192.168.1.1",
    "ports": "1-1000",
    "throttleMs": 100
  }
}

API测试

{
  "name": "test_api",
  "arguments": {
    "url": "https://api.example.com/health",
    "method": "GET",
    "expectedStatus": 200
  }
}

TLS证书检查

{
  "name": "test_tls",
  "arguments": {
    "target": "example.com",
    "port": 443
  }
}

交互式CLI客户端

对于本地测试和开发，该项目包括一个全面的交互式命令行客户端，无需在开发和测试阶段进行云部署。

特性

• 🎨 丰富的终端用户界面：带有格式化表格和结构化数据的彩色输出
• 🔐 内置身份验证：具有用户标识和角色的单个JWT令牌
• 📋 交互式工具选择：所有14个网络工具的菜单驱动界面
• ✅ 参数验证：通过验证和确认引导输入
• 📊 格式化结果：具有执行时间的干净、结构化的输出
• ⚡ 实时反馈：进度指标和状态更新

快速开始

# Development mode (recommended for testing)
npm run dev:client

# Or build and run
npm run build
npm run client

认证

客户端支持多种身份验证方法：

# Method 1: Environment variable (recommended)
export AUTH_TOKEN="your-jwt-token"
npm run dev:client

# Method 2: Interactive prompt (client will ask for token)
npm run dev:client

生成身份验证令牌

# Global install:
mcp-network-generate-token  
# Example: mcp-network-generate-token cli-user admin

# Source install:
npm run build
npm run config generate-token
# Or directly: npm run generate-token  

交互式会话示例

╔═══════════════════════════════════════════╗
║     MCP Network Testing Client            ║
║     Interactive Command Line Interface    ║
╚═══════════════════════════════════════════╝

✓ Connected to MCP server (14 tools available)

📋 Available Tools

1. ping - Send ICMP echo requests to test host reachability
2. traceroute - Trace the network path to a destination  
3. dns_lookup - Query DNS records for a domain
4. whois - Get domain registration information
5. ip_geolocation - Get geolocation data for IP addresses
...

? Select a tool to execute: ping

📝 Parameters for ping
? * target (Hostname or IP address): example.com  
? * count (Number of packets, 1-10): 4

📋 Execution Summary:
Tool: ping
Parameters: { target: "example.com", count: 4 }

? Execute this tool? Yes

⏳ Executing ping...
✓ ping completed (1.2s)

╔════════════════╗
║   ✓ SUCCESS    ║  
╚════════════════╝

Results:
host: example.com
packetsTransmitted: 4
packetsReceived: 4  
packetLoss: 0%
avgRtt: 25.3ms

? Execute another tool? No

对地方发展的益处

• 无需云部署：在开发过程中在本地测试所有功能
• 快速迭代：即时反馈，无需部署周期
• 安全测试：在不公开服务的情况下尝试使用工具
• 开发工作流程：非常适合调试和功能开发
• 成本有效：初始测试和验证不需要云实例

客户端体系结构

CLI客户端由模块化组件组成：

• 交互界面 (index.ts)：主编排和用户流
• MCP连接 (connection.ts)：服务器通信和工具执行
• 参数提示 (prompts.ts)：用户输入收集和验证
• 结果格式化程序 (formatter.ts)：彩色输出和数据呈现

这种设计允许交互式使用和潜在的自动化/脚本集成。

🌐 REST API服务器

除了MCP协议和交互式CLI之外，服务器还提供了一个完整的REST API，用于通过HTTP/HTTPS访问所有14个网络测试工具。这使得与不支持MCP的web应用程序、自动化脚本和AI代理集成变得容易。

特性

• 🔒 JWT身份验证：与MCP服务器相同的身份验证系统
• 📖 交互式文档：用于API勘探和测试的Swagger UI
• 🛡️ 安全：Helmet.js、CORS、压缩和速率限制
• 🎯 全覆盖：通过REST端点公开的所有14个工具
• 📊 结构化响应：一致的JSON响应格式
• ⚡ 健康检查：用于监视的未经身份验证的端点

快速开始

# Option 1: Run API server only
npm run dev:api

# Option 2: Run both MCP and REST API servers (recommended)
npm run dev:both

# Access interactive documentation
open http://localhost:3001/api-docs

# Test an endpoint
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/tools

注： 使用 npm run dev:both 同时运行MCP服务器（stdio）和REST API服务器（HTTP），这是全栈开发和测试的理想选择。

配置

通过中的环境变量配置REST API服务器 .env:

API_PORT=3001                      # REST API server port (default: 3000)
API_ENABLED=true                   # Enable/disable API server
API_RATE_LIMIT_MAX=100             # Max requests per window
API_RATE_LIMIT_WINDOW_MS=60000     # Rate limit window (1 minute)

API调用示例

Ping主机：

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"google.com","count":4}' \
  http://localhost:3001/api/tools/ping

DNS查找：

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com","recordType":"A"}' \
  http://localhost:3001/api/tools/dns_lookup

端口扫描：

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"192.168.1.1","ports":"22,80,443"}' \
  http://localhost:3001/api/tools/port_scan

API 文档

有关完整的API文档，包括所有端点、请求/响应格式、错误处理和生产部署指南，请参阅 docs/API_README.md文件.

何时使用REST API

适用于：

• WEB应用集成
• 自动化脚本（Python、JavaScript等）
• 不支持MCP的AI代理
• Webhook集成
• CI/CD管道
• 监测和警报系统

请改用MCP协议：

• Claude桌面集成
• 本地MCP客户端应用程序
• 实时双向通信
• 降低通信开销

💡 真实世界用例

AI代理服务器配置场景

场景1:带SSL设置的NGINX

Agent Task: "Configure NGINX with Let's Encrypt SSL for example.com"

AI Agent Workflow with MCP Network Server:
1. Agent generates NGINX configuration
2. Uses `letsencrypt` tool to obtain SSL certificate
3. Uses `tls_test` tool to verify certificate installation
4. Uses `port_test` tool to confirm ports 80/443 are accessible  
5. Uses `dns_lookup` tool to verify domain points to server
6. Agent iterates configuration based on test results

场景2:VPN服务器验证

Agent Task: "Set up WireGuard VPN with proper routing"

AI Agent Workflow:
1. Agent configures WireGuard server and routing tables
2. Uses `ip_address` tool to get server's public IP
3. Uses `port_test` tool to verify VPN port accessibility
4. Uses `ping` tool to test connectivity through VPN tunnel
5. Uses `traceroute` tool to verify routing paths
6. Agent adjusts firewall rules based on connectivity tests

场景3：邮件服务器配置

Agent Task: "Configure Postfix SMTP server with proper DNS records"

AI Agent Workflow:
1. Agent sets up Postfix configuration
2. Uses `dns_lookup` tool to verify MX records
3. Uses `reverse_dns` tool to check PTR records
4. Uses `port_test` tool to verify SMTP ports (25, 587, 465)
5. Uses `tls_test` tool to validate SMTP TLS configuration
6. Agent fine-tunes configuration based on DNS and connectivity results

场景4：负载平衡器运行状况检查

Agent Task: "Configure HAProxy with health monitoring"

AI Agent Workflow:
1. Agent generates HAProxy configuration with backend servers
2. Uses `ping` tool to verify backend server connectivity
3. Uses `port_test` tool to check backend service ports
4. Uses `test_api` tool to validate HTTP health check endpoints
5. Uses `tls_test` tool for HTTPS backend verification
6. Agent adjusts backend weights and health check intervals

优于传统方法的优势

没有MCP网络服务器：

• 代理生成配置→ 人工测试→ 人工向代理报告→ 代理调整
• 多个手动干预周期
• 测试中容易出现人为错误
• 迭代周期缓慢

使用MCP网络服务器：

• 代理生成配置→ 代理自动测试→ 代理自我更正→ 重复直到成功
• 全自动验证循环
• 一致、可重复的测试
• 快速迭代和收敛

性能和限制

资源使用情况

• 记忆：典型使用率\ 免责声明： 以下列出的云提供商产品和免费等级规范截至2025年11月是准确的，如有更改，恕不另行通知。此信息仅供参考。始终直接与您选择的云提供商核实当前的定价、可用性和条款。

合适的免费等级选项：

Oracle云始终免费：

• ARM Ampere A1 Compute（4个OCPU，24GB RAM）-规格丰富，非常适合此用例
• VM。标准。E2.1.Micro（1个OCPU，1GB RAM）-足够MCP服务器使用

AWS免费套餐：

• t2.micro（1个vCPU，1GB RAM）-每月750小时，持续12个月
• t3.micro（2个vCPU，1GB RAM）-更好的性能选项

谷歌云免费套餐：

• e2 micro（2个vCPU，1GB RAM）-在特定地区始终可用
• f1微型（1个vCPU，0.6GB RAM）-最小但功能齐全

Azure免费等级：

• B1S（1个vCPU，1GB RAM）-每月750小时，持续12个月

即使是最小的实例也提供了足够多的资源来运行MCP服务器和基本系统服务。服务器的高效设计确保了可靠的运行，而不会消耗大量的系统资源。

安全

⚠️ 重要安全注意事项

虽然此MCP服务器实现了不错的安全措施，包括JWT身份验证、输入验证和防越狱保护，但将其部署在任何公开的系统（云提供商、VPS等）上都会引入固有的安全风险。

安全扫描

此项目使用 Semgrep 对于自动安全漏洞扫描：

npm run semgrep

扫描结果: ✅ 发现0个漏洞（245条规则，扫描了45个文件）

TLS验证说明：The tls-test 工具故意使用 rejectUnauthorized: false 检查TLS证书，无论其有效性如何。这是诊断工具的预期行为（类似于 openssl s_client, curl -k，或 nmap ssl-enum-ciphers).该连接仅用于检索证书元数据，并立即关闭，不会传输任何敏感数据。这已在semgrep中记录并压制，并给出了适当的理由。

强烈推荐的安全措施：

网络级保护：

• 配置云提供商安全组/防火墙，仅限制对基本端口的访问

- MCP服务器：stdio传输（无需端口暴露） - REST API服务器：端口3001（或已配置 API_PORT)

• 使用CIDR块实现IP白名单，以限制对已知网络的访问
• 考虑仅使用VPN访问以获得最大安全性
• 在生产中为REST API使用HTTPS反向代理（nginx/Apache）

实例级安全：

• 启用和配置本地防火墙（iptables、ufw、Windows防火墙）
• 定期更新操作系统和所有依赖项
• 使用非root用户运行服务
• 实施fail2ban或类似的入侵检测系统

访问控制：

• 使用来自的自动生成的安全凭据 mcp-network-setup
• 如果令牌受到损害，请通过运行以下命令重新生成它们 mcp-network-setup 再次（使所有现有令牌无效）
• 监控访问日志中的可疑活动（包括令牌中的用户ID）
• 考虑在网络级别实施额外的速率限制

最佳实践： 将MCP服务器部署在只能通过堡垒主机或VPN连接访问的专用子网中，而不是将其直接暴露在互联网上。

发展

项目结构

src/
├── index.ts              # Main MCP server entry point
├── types/                # TypeScript type definitions
├── auth/                 # JWT authentication and RBAC
├── middleware/           # Validation and guardrails
├── tools/                # Individual tool implementations (14 tools)
├── utils/                # Helper functions
├── logger/               # Logging system
├── client/               # Interactive CLI client
│   ├── index.ts          # CLI entry point
│   ├── connection.ts     # MCP connection management
│   ├── prompts.ts        # Interactive prompts
│   └── formatter.ts      # Result formatting
├── rest-api/             # REST API server
│   ├── server.ts         # Express server entry point
│   ├── middleware/       # Auth and error handling
│   ├── routes/           # API routes (health, tools)
│   └── swagger.ts        # OpenAPI specification
├── config/               # Configuration CLI
└── __tests__/            # Test suites (MCP + REST API)

运行测试

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

代码检查

npm run lint
npm run lint:fix

系统要求

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y \
  iputils-ping \
  traceroute \
  dnsutils \
  whois \
  nmap \
  tcpdump \
  iperf3

RHEL/CentOS

sudo yum install -y \
  iputils \
  traceroute \
  bind-utils \
  whois \
  nmap \
  tcpdump \
  iperf3

macOS

brew install \
  nmap \
  tcpdump \
  iperf3 \
  whois

故障排除

权限被拒绝错误

某些工具（nmap SYN扫描、tcpdump）需要root权限：

# Run with sudo
sudo npm start

# Or use capabilities (Linux)
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/tcpdump

身份验证错误

确保您的JWT令牌有效：

# Decode token to see its contents
node -e "const jwt = require('jsonwebtoken'); console.log(jwt.decode(process.env.AUTH_TOKEN));"

# Or regenerate token (global install)
mcp-network-generate-token  

# Or regenerate token (source install)
npm run config generate-token

未找到工具

验证是否安装了所需的系统工具：

which ping traceroute dig whois nmap tcpdump iperf3

npm弃用警告

在安装过程中，您可能会看到以下软件包的弃用警告：

npm warn deprecated inflight@1.0.6
npm warn deprecated lodash.get@4.4.2
npm warn deprecated lodash.isequal@4.5.0
npm warn deprecated glob@7.1.6

这些是可以忽略的。 所有已弃用的包都是源于以下内容的可传递依赖项（依赖项的依赖项） swagger-jsdoc@6.2.8，仅用于生成API文档。它们不影响：

• 生产运行时行为
• 应用程序安全
• 核心功能

依赖链：

• swagger-jsdoc@6.2.8 → glob@7.1.6 → inflight@1.0.6
• swagger-jsdoc@6.2.8 → swagger-parser → z-schema → lodash.get, lodash.isequal

未来决议： 我们正在监控 swagger-jsdoc v7.0.0（目前处于候选版本中）解决了这些弃用问题。一旦v7.0.0稳定，我们将升级以消除这些警告。

贡献

此项目遵循安全最佳实践。贡献时：

1. 验证所有输入
2. 实施适当的错误处理
3. 添加综合测试
4. 文档安全注意事项
5. 遵循现有代码样式

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

• GitHub问题：https://github.com/robursoft/mcp-network/issues
• 文件：见 文档/部署.md 用于部署指南

路线图

• \[\]VPN测试（OpenVPN、WireGuard、IPSec）
• \[\]WebSocket测试
• \[\]SSH连接测试
• \[\]数据库连接测试
• \[\]云提供商集成（AWS、Azure）
• \[\]增强的Let’s Encrypt自动化
• \[\]用于管理的Web UI
• \[\]普罗米修斯指标导出
• \[\]具有适当功能的Docker容器

安全披露

如果您发现安全漏洞，请发送电子邮件至security@robursoft.com而不是使用问题跟踪器。