VPS Execute MCP

VPS执行MCP

MCP服务器+REST API，用于AI代理通过SSH与远程主机交互

通过Claude Desktop等人工智能代理或通过REST API执行命令、管理文件并监控远程服务器。

🚀 特性

MCP服务器（模型上下文协议）

• ✅ 与Claude Desktop和其他MCP客户端的本地集成
• ✅ AI代理的结构化工具发现
• ✅ 使用JSON模式进行类型安全的输入/输出
• ✅ 实时命令执行流

REST API

• ✅ 任何客户端的HTTP端点
• ✅ API密钥验证
• ✅ 速率限制和安全控制
• ✅ 全面的审计日志记录

核心能力

• 🔧 执行命令 -在远程主机上运行shell命令
• 📁 文件操作 -通过SFTP上传、下载和列出文件
• 📊 系统监控 -获取系统信息、资源使用情况和正在运行的进程
• 🔐 安全 -SSH密钥认证、命令白名单、速率限制
• 📝 审计日志 -所有操作的完整审计跟踪

📋 快速开始

1.安装

# Clone the repository
git clone https://github.com/yourusername/VPS-Execute-MCP.git
cd VPS-Execute-MCP

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your SSH credentials

# Build
npm run build

2.配置

编辑 .env 文件：

SSH_HOST=your-server.com
SSH_PORT=22
SSH_USERNAME=your-username
SSH_PRIVATE_KEY_PATH=/path/to/your/private/key

API_PORT=3000
API_KEY=your-secure-api-key-change-this

3.运行服务器

选项A:MCP服务器（适用于克劳德桌面）

npm run mcp

选项B:REST API服务器

npm run api

🤖 与Claude Desktop一起使用

配置

添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vps-execute": {
      "command": "node",
      "args": ["/absolute/path/to/VPS-Execute-MCP/dist/mcp-server.js"],
      "env": {
        "SSH_HOST": "your-server.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "your-username",
        "SSH_PRIVATE_KEY_PATH": "/home/user/.ssh/id_rsa"
      }
    }
  }
}

重新启动Claude Desktop，然后尝试：

“检查远程服务器上的磁盘使用情况”

看 CLAUDE_DESKTOP.md 详细说明。

🌐 使用REST API

执行命令

curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"command": "df -h"}'

获取系统信息

curl http://localhost:3000/system-info \
  -H "X-API-Key: your-api-key"

上传文件

curl -X POST http://localhost:3000/upload \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "localPath": "/tmp/config.json",
    "remotePath": "/etc/app/config.json"
  }'

看 API_DOCUMENTATION.md 以获取完整的API参考。

🔐 安全功能

• SSH密钥认证 -基于安全密钥的SSH访问
• API密钥保护 -所有REST API端点都需要身份验证
• 命令白名单 -限制允许的命令（可选）
• 速率限制 -防止滥用（默认100个请求/分钟）
• 危险模式检测 -阻止可能有害的命令
• 审计日志 -所有操作的完整跟踪
• 超时保护 -防止命令失控

启用命令白名单

ENABLE_COMMAND_WHITELIST=true
ALLOWED_COMMANDS=ls,pwd,df,free,top,ps,cat,grep

📖 文档

• 设置.md -详细的设置和安装指南
• CLAUDE_DESKTOP.md -Claude桌面集成指南
• API_DOCUMENTATION.md -完整的REST API参考

🛠️ 可用工具/端点

🏗️ 建筑

┌─────────────────────────────────────────┐
│    AI Agent (Claude Desktop, etc.)     │
└────────┬────────────────────────┬───────┘
         │ MCP Protocol           │ HTTP/REST
┌────────▼────────┐      ┌────────▼────────┐
│   MCP Server    │      │   API Server    │
│   (stdio)       │      │   (Express)     │
└────────┬────────┘      └────────┬────────┘
         │                        │
         └────────┬───────────────┘
                  │
         ┌────────▼────────┐
         │  SSH Manager    │
         │  (ssh2/sftp)    │
         └────────┬────────┘
                  │ SSH/SFTP
         ┌────────▼────────┐
         │  Remote Host    │
         └─────────────────┘

🧪 发展

# Install dependencies
npm install

# Run in development mode with auto-reload
npm run dev

# Type checking
npm run type-check

# Build
npm run build

📝 示例用例

使用Claude进行服务器监控

克劳德，检查我的服务器的CPU和内存使用情况，如果有什么异常，请告诉我

自动化部署

“将新的配置文件上传到/etc/myapp/并重新启动服务”

日志分析

“下载nginx错误日志的最后1000行并总结主要问题”

系统维护

“检查/var/中哪些目录使用了最多的磁盘空间”

与自定义AI代理集成

import requests

def check_server_health(api_key):
    response = requests.get(
        "http://localhost:3000/system-info",
        headers={"X-API-Key": api_key}
    )
    return response.json()

⚠️ 安全警告

• 未经正确身份验证，切勿将API服务器直接暴露在互联网上
• 始终使用SSH密钥身份验证而不是密码
• 在生产环境中启用命令白名单
• 定期审查审计日志
• 使用具有有限权限的专用SSH用户
• 确保API密钥的安全并定期轮换

📄 许可证

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

🤝 贡献

欢迎投稿！请打开问题或提交拉取请求。

📧 支持

• 文件：见 docs/ 文件夹
• 问题：
• 安全：请私下报告安全问题

🙏 致谢

• 与 模型上下文协议SDK
• 用途 ssh2 用于SSH连接
• 由...驱动 快速 用于REST API