mcp-ssh-server-tool 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# SSH MCP Server
+
+一个用于 SSH 连接和远程命令执行的 MCP (Model Context Protocol) 服务器。
+
+## 功能
+
+- 🔐 **密码认证** - 使用用户名和密码连接到 SSH 服务器
+- 🔑 **公钥认证** - 使用私钥文件连接到 SSH 服务器
+- 💻 **远程命令执行** - 在连接的服务器上执行命令并获取输出
+- 📊 **会话管理** - 管理多个 SSH 连接会话
+
+## MCP 工具
+
+### ssh_connect
+建立 SSH 连接
+
+**参数：**
+- `host`: 服务器地址 (必需)
+- `port`: 端口号 (默认: 22)
+- `username`: 用户名 (必需)
+- `auth_type`: 认证方式 - "password" | "public_key" (必需)
+- `password`: 密码 (auth_type 为 password 时必需)
+- `private_key_path`: 私钥路径 (auth_type 为 public_key 时必需)
+- `passphrase`: 私钥密码 (可选)
+- `timeout`: 连接超时 (默认: 10秒)
+
+### ssh_exec
+在 SSH 会话中执行命令
+
+**参数：**
+- `session_id`: SSH 会话 ID (必需)
+- `command`: 要执行的命令 (必需)
+
+**返回：**
+- `stdout`: 标准输出
+- `stderr`: 标准错误
+- `exit_code`: 退出码
+
+### ssh_disconnect
+断开 SSH 连接
+
+**参数：**
+- `session_id`: SSH 会话 ID (必需)
+
+### ssh_list_sessions
+列出所有活动的 SSH 会话
+
+## 安装
+
+### 步骤 1: 安装依赖
+
+在终端中运行：
+```bash
+pip install paramiko mcp
+```
+
+### 步骤 2: 安装 SSH MCP Server
+
+```bash
+pip install -e .
+```
+
+## 配置
+
+### 重要: 确保依赖已安装
+
+在使用 MCP 之前，请确保你的 AI 客户端使用的 Python 环境中已安装依赖：
+
+```bash
+pip install paramiko mcp
+```
+
+### Claude Desktop 配置
+
+在 Claude Desktop 的配置文件中添加：
+
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "ssh-mcp-server": {
+      "command": "python",
+      "args": ["-m", "mcp_ssh_server.index"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Cursor / VS Code 配置
+
+在 `.cursor/mcp.json` 或 `.vscode/mcp.json` 中添加相同配置：
+
+```json
+{
+  "mcpServers": {
+    "ssh-mcp-server": {
+      "command": "python",
+      "args": ["-m", "mcp_ssh_server.index"],
+      "env": {}
+    }
+  }
+}
+```
+
+### 故障排除
+
+如果遇到 `Connection closed` 错误：
+
+1. **确认依赖已安装**:
+   ```bash
+   python -c "import paramiko; import mcp; print('OK')"
+   ```
+
+2. **检查 Python 路径**: 在终端中运行以下命令获取 Python 路径，并在配置中使用完整路径：
+   ```bash
+   where python   # Windows
+   which python   # Linux/Mac
+   ```
+
+3. **使用完整路径配置**:
+   ```json
+   {
+     "mcpServers": {
+       "ssh-mcp-server": {
+         "command": "C:\\Users\\你的用户名\\anaconda3\\python.exe",
+         "args": ["-m", "mcp_ssh_server.index"],
+         "env": {}
+       }
+     }
+   }
+   ```
+
+## 使用示例
+
+### 1. 密码认证连接
+
+```json
+{
+  "host": "192.168.1.100",
+  "port": 22,
+  "username": "admin",
+  "auth_type": "password",
+  "password": "your_password"
+}
+```
+
+### 2. 公钥认证连接
+
+```json
+{
+  "host": "192.168.1.100",
+  "port": 22,
+  "username": "admin",
+  "auth_type": "public_key",
+  "private_key_path": "C:\\Users\\you\\.ssh\\id_rsa"
+}
+```
+
+### 3. 执行命令
+
+```json
+{
+  "session_id": "<从 ssh_connect 返回的 session_id>",
+  "command": "ls -la /home"
+}
+```
+
+### 4. 断开连接
+
+```json
+{
+  "session_id": "<session_id>"
+}
+```
+
+## 项目结构
+
+```
+SSH-MCP/
+├── mcp_ssh_server/
+│   ├── __init__.py
+│   ├── index.py          # MCP Server 主入口
+│   └── ssh_manager.py    # SSH 连接管理器
+├── pyproject.toml        # Python 项目配置
+├── mcp.json             # MCP 配置文件示例
+└── README.md            # 使用说明
+```
+
+## 依赖
+
+- Python >= 3.10
+- paramiko >= 3.4.0
+- mcp >= 1.1.0
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,500 @@
+import { Client } from 'ssh2';
+import { v4 as uuidv4 } from 'uuid';
+import * as fs from 'fs';
+
+class SSHSession {
+  constructor(sessionId, client, host, username) {
+    this.sessionId = sessionId;
+    this.client = client;
+    this.host = host;
+    this.username = username;
+    this.connected = true;
+  }
+}
+
+class SSHConnectionManager {
+  constructor() {
+    this.sessions = new Map();
+  }
+
+  connect(options) {
+    return new Promise((resolve) => {
+      const client = new Client();
+      const sessionId = uuidv4();
+      const port = options.port || 22;
+      const timeout = (options.timeout || 10) * 1000;
+
+      const config = {
+        host: options.host,
+        port: port,
+        username: options.username,
+        timeout: timeout,
+        readyTimeout: timeout,
+      };
+
+      if (options.authType === 'password') {
+        if (!options.password) {
+          resolve({
+            success: false,
+            error: 'Password is required for password authentication',
+            errorType: 'MissingPassword',
+          });
+          return;
+        }
+        config.password = options.password;
+      } else if (options.authType === 'public_key') {
+        if (!options.privateKeyPath) {
+          resolve({
+            success: false,
+            error: 'Private key path is required for public key authentication',
+            errorType: 'MissingPrivateKey',
+          });
+          return;
+        }
+        try {
+          config.privateKey = fs.readFileSync(options.privateKeyPath);
+          if (options.passphrase) {
+            config.passphrase = options.passphrase;
+          }
+        } catch (err) {
+          resolve({
+            success: false,
+            error: `Failed to read private key: ${err.message}`,
+            errorType: 'PrivateKeyError',
+          });
+          return;
+        }
+      }
+
+      client.on('ready', () => {
+        const session = new SSHSession(sessionId, client, options.host, options.username);
+        this.sessions.set(sessionId, session);
+
+        resolve({
+          success: true,
+          sessionId,
+          host: options.host,
+          port,
+          username: options.username,
+          message: `Successfully connected to ${options.host}:${port}`,
+        });
+      });
+
+      client.on('error', (err) => {
+        resolve({
+          success: false,
+          error: err.message,
+          errorType: 'ConnectionError',
+        });
+      });
+
+      client.connect(config);
+    });
+  }
+
+  execCommand(sessionId, command) {
+    const session = this.sessions.get(sessionId);
+
+    if (!session) {
+      return {
+        success: false,
+        error: `Session ${sessionId} not found`,
+        errorType: 'SessionNotFound',
+      };
+    }
+
+    if (!session.connected) {
+      return {
+        success: false,
+        error: `Session ${sessionId} is not connected`,
+        errorType: 'SessionNotConnected',
+      };
+    }
+
+    return new Promise((resolve) => {
+      session.client.exec(command, (err, stream) => {
+        if (err) {
+          resolve({
+            success: false,
+            error: err.message,
+            errorType: 'ExecError',
+            sessionId,
+          });
+          return;
+        }
+
+        let stdout = '';
+        let stderr = '';
+
+        stream.on('close', (code) => {
+          resolve({
+            success: true,
+            sessionId,
+            command,
+            stdout,
+            stderr,
+            exitCode: code,
+          });
+        });
+
+        stream.on('data', (data) => {
+          stdout += data.toString();
+        });
+
+        stream.stderr.on('data', (data) => {
+          stderr += data.toString();
+        });
+      });
+    });
+  }
+
+  disconnect(sessionId) {
+    const session = this.sessions.get(sessionId);
+
+    if (!session) {
+      return {
+        success: false,
+        error: `Session ${sessionId} not found`,
+        errorType: 'SessionNotFound',
+      };
+    }
+
+    try {
+      session.client.end();
+      session.connected = false;
+      this.sessions.delete(sessionId);
+
+      return {
+        success: true,
+        sessionId,
+        message: 'Disconnected successfully',
+      };
+    } catch (err) {
+      return {
+        success: false,
+        error: err.message,
+        errorType: 'DisconnectError',
+      };
+    }
+  }
+
+  listSessions() {
+    const sessions = [];
+
+    this.sessions.forEach((session) => {
+      sessions.push({
+        sessionId: session.sessionId,
+        host: session.host,
+        username: session.username,
+        connected: session.connected,
+      });
+    });
+
+    return {
+      success: true,
+      sessions,
+      count: sessions.length,
+    };
+  }
+}
+
+const sshManager = new SSHConnectionManager();
+
+const tools = [
+  {
+    name: 'ssh_connect',
+    description: 'Establish an SSH connection to a remote server',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        host: {
+          type: 'string',
+          description: 'Server hostname or IP address',
+        },
+        port: {
+          type: 'number',
+          description: 'SSH port number',
+          default: 22,
+        },
+        username: {
+          type: 'string',
+          description: 'SSH username',
+        },
+        auth_type: {
+          type: 'string',
+          enum: ['password', 'public_key'],
+          description: 'Authentication type',
+        },
+        password: {
+          type: 'string',
+          description: 'Password (required if auth_type is password)',
+        },
+        private_key_path: {
+          type: 'string',
+          description: 'Path to private key file (required if auth_type is public_key)',
+        },
+        passphrase: {
+          type: 'string',
+          description: 'Passphrase for private key (optional)',
+        },
+        timeout: {
+          type: 'number',
+          description: 'Connection timeout in seconds',
+          default: 10,
+        },
+      },
+      required: ['host', 'username', 'auth_type'],
+    },
+  },
+  {
+    name: 'ssh_exec',
+    description: 'Execute a command on an active SSH session',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'The SSH session ID from ssh_connect',
+        },
+        command: {
+          type: 'string',
+          description: 'The command to execute',
+        },
+      },
+      required: ['session_id', 'command'],
+    },
+  },
+  {
+    name: 'ssh_disconnect',
+    description: 'Disconnect an SSH session',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'The SSH session ID to disconnect',
+        },
+      },
+      required: ['session_id'],
+    },
+  },
+  {
+    name: 'ssh_list_sessions',
+    description: 'List all active SSH sessions',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+];
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + '\n');
+}
+
+let buffer = '';
+
+process.stdin.setEncoding('utf8');
+
+process.stdin.on('data', (chunk) => {
+  buffer += chunk;
+  let newlineIndex;
+
+  while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+    const line = buffer.slice(0, newlineIndex);
+    buffer = buffer.slice(newlineIndex + 1);
+
+    if (line.trim()) {
+      try {
+        const request = JSON.parse(line);
+        handleRequest(request);
+      } catch (err) {
+        console.error('Parse error:', err);
+      }
+    }
+  }
+});
+
+function handleRequest(request) {
+  const { id, method, params } = request;
+
+  if (method === 'initialize') {
+    send({
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: {
+          name: 'ssh-mcp-server',
+          version: '1.0.0',
+        },
+      },
+    });
+    return;
+  }
+
+  if (method === 'notifications/initialized') {
+    return;
+  }
+
+  if (method === 'tools/list') {
+    send({
+      jsonrpc: '2.0',
+      id,
+      result: { tools },
+    });
+    return;
+  }
+
+  if (method === 'tools/call') {
+    const { name, arguments: args } = params;
+
+    // Handle nested arguments (stringified JSON)
+    let toolArgs = args;
+    if (typeof args === 'string') {
+      try {
+        toolArgs = JSON.parse(args);
+      } catch (e) {
+        toolArgs = {};
+      }
+    } else if (args && typeof args.arguments === 'string') {
+      try {
+        toolArgs = JSON.parse(args.arguments);
+      } catch (e) {
+        toolArgs = args;
+      }
+    }
+
+    if (name === 'ssh_connect') {
+      sshManager.connect({
+        host: toolArgs.host,
+        port: toolArgs.port,
+        username: toolArgs.username,
+        authType: toolArgs.auth_type,
+        password: toolArgs.password,
+        privateKeyPath: toolArgs.private_key_path,
+        passphrase: toolArgs.passphrase,
+        timeout: toolArgs.timeout,
+      }).then((result) => {
+        send({
+          jsonrpc: '2.0',
+          id,
+          result: {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(result),
+              },
+            ],
+          },
+        });
+      });
+      return;
+    }
+
+    if (name === 'ssh_exec') {
+      const execResult = sshManager.execCommand(toolArgs.session_id, toolArgs.command);
+      if (execResult && typeof execResult.then === 'function') {
+        execResult.then((result) => {
+          send({
+            jsonrpc: '2.0',
+            id,
+            result: {
+              content: [
+                {
+                  type: 'text',
+                  text: JSON.stringify(result),
+                },
+              ],
+            },
+          });
+        }).catch((err) => {
+          send({
+            jsonrpc: '2.0',
+            id,
+            result: {
+              content: [
+                {
+                  type: 'text',
+                  text: JSON.stringify({ success: false, error: err.message }),
+                },
+              ],
+            },
+          });
+        });
+      } else {
+        send({
+          jsonrpc: '2.0',
+          id,
+          result: {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(execResult),
+              },
+            ],
+          },
+        });
+      }
+      return;
+    }
+
+    if (name === 'ssh_disconnect') {
+      const result = sshManager.disconnect(toolArgs.session_id);
+      send({
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result),
+            },
+          ],
+        },
+      });
+      return;
+    }
+
+    if (name === 'ssh_list_sessions') {
+      const result = sshManager.listSessions();
+      send({
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result),
+            },
+          ],
+        },
+      });
+      return;
+    }
+
+    send({
+      jsonrpc: '2.0',
+      id,
+      result: {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ success: false, error: `Unknown tool: ${name}` }),
+          },
+        ],
+      },
+    });
+    return;
+  }
+
+  send({
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code: -32601,
+      message: 'Method not found',
+    },
+  });
+}

package/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "ssh-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "mcp-ssh-server-tool"],
+      "env": {},
+      "description": "SSH MCP Server - Connect to remote servers via SSH and execute commands"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "mcp-ssh-server-tool",
+  "version": "1.0.0",
+  "description": "MCP Server for SSH connections and remote command execution",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "mcp-ssh-server-tool": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["mcp", "ssh", "server", "mcp-server", "remote-execution"],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dependencies": {
+    "ssh2": "^1.15.0",
+    "uuid": "^9.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "preferGlobal": true
+}

package/ssh_manager.js

@@ -0,0 +1,199 @@
+import { Client } from 'ssh2';
+import { v4 as uuidv4 } from 'uuid';
+import * as fs from 'fs';
+
+class SSHSession {
+  constructor(sessionId, client, host, username) {
+    this.sessionId = sessionId;
+    this.client = client;
+    this.host = host;
+    this.username = username;
+    this.connected = true;
+  }
+}
+
+export class SSHConnectionManager {
+  constructor() {
+    this.sessions = new Map();
+  }
+
+  connect(options) {
+    return new Promise((resolve) => {
+      const client = new Client();
+      const sessionId = uuidv4();
+      const port = options.port || 22;
+      const timeout = (options.timeout || 10) * 1000;
+
+      const config = {
+        host: options.host,
+        port: port,
+        username: options.username,
+        timeout: timeout,
+        readyTimeout: timeout,
+      };
+
+      if (options.authType === 'password') {
+        if (!options.password) {
+          resolve({
+            success: false,
+            error: 'Password is required for password authentication',
+            errorType: 'MissingPassword',
+          });
+          return;
+        }
+        config.password = options.password;
+      } else if (options.authType === 'public_key') {
+        if (!options.privateKeyPath) {
+          resolve({
+            success: false,
+            error: 'Private key path is required for public key authentication',
+            errorType: 'MissingPrivateKey',
+          });
+          return;
+        }
+        try {
+          config.privateKey = fs.readFileSync(options.privateKeyPath);
+          if (options.passphrase) {
+            config.passphrase = options.passphrase;
+          }
+        } catch (err) {
+          resolve({
+            success: false,
+            error: `Failed to read private key: ${err.message}`,
+            errorType: 'PrivateKeyError',
+          });
+          return;
+        }
+      }
+
+      client.on('ready', () => {
+        const session = new SSHSession(sessionId, client, options.host, options.username);
+        this.sessions.set(sessionId, session);
+
+        resolve({
+          success: true,
+          sessionId,
+          host: options.host,
+          port,
+          username: options.username,
+          message: `Successfully connected to ${options.host}:${port}`,
+        });
+      });
+
+      client.on('error', (err) => {
+        resolve({
+          success: false,
+          error: err.message,
+          errorType: 'ConnectionError',
+        });
+      });
+
+      client.connect(config);
+    });
+  }
+
+  execCommand(sessionId, command) {
+    const session = this.sessions.get(sessionId);
+
+    if (!session) {
+      return {
+        success: false,
+        error: `Session ${sessionId} not found`,
+        errorType: 'SessionNotFound',
+      };
+    }
+
+    if (!session.connected) {
+      return {
+        success: false,
+        error: `Session ${sessionId} is not connected`,
+        errorType: 'SessionNotConnected',
+      };
+    }
+
+    return new Promise((resolve) => {
+      session.client.exec(command, (err, stream) => {
+        if (err) {
+          resolve({
+            success: false,
+            error: err.message,
+            errorType: 'ExecError',
+            sessionId,
+          });
+          return;
+        }
+
+        let stdout = '';
+        let stderr = '';
+
+        stream.on('close', (code) => {
+          resolve({
+            success: true,
+            sessionId,
+            command,
+            stdout,
+            stderr,
+            exitCode: code,
+          });
+        });
+
+        stream.on('data', (data) => {
+          stdout += data.toString();
+        });
+
+        stream.stderr.on('data', (data) => {
+          stderr += data.toString();
+        });
+      });
+    });
+  }
+
+  disconnect(sessionId) {
+    const session = this.sessions.get(sessionId);
+
+    if (!session) {
+      return {
+        success: false,
+        error: `Session ${sessionId} not found`,
+        errorType: 'SessionNotFound',
+      };
+    }
+
+    try {
+      session.client.end();
+      session.connected = false;
+      this.sessions.delete(sessionId);
+
+      return {
+        success: true,
+        sessionId,
+        message: 'Disconnected successfully',
+      };
+    } catch (err) {
+      return {
+        success: false,
+        error: err.message,
+        errorType: 'DisconnectError',
+      };
+    }
+  }
+
+  listSessions() {
+    const sessions = [];
+
+    this.sessions.forEach((session) => {
+      sessions.push({
+        sessionId: session.sessionId,
+        host: session.host,
+        username: session.username,
+        connected: session.connected,
+      });
+    });
+
+    return {
+      success: true,
+      sessions,
+      count: sessions.length,
+    };
+  }
+}