SSH MCP Server

# SSH MCP Server Advanced SSH Session Manager for Model Context Protocol (MCP) with multi-session support and connection monitoring. ## Features - **Multi-Session Management**: Create and manage multiple SSH connections simultaneously - **Session Monitoring**: Automatic connection health checks and timeout management - **Command Execution**: Execute commands on remote servers with timeout control - **Session Persistence**: Maintain long-running SSH sessions with metadata tracking - **Automatic Cleanup**: Intelligent session cleanup based on usage and timeouts ## Installation ### Prerequisites - Python 3.11+ - UV package manager - Claude Desktop ### Setup with UV 1. Clone or download this project: ```bash git clone <repository-url> cd ssh_mcp ``` 2. Install dependencies: ```bash uv sync ``` 3. Test the installation: ```bash uv run python main.py ``` ## Claude Desktop Configuration ### 1. Locate Claude Desktop Config File **Windows:** ``` %APPDATA%\Claude\claude_desktop_config.json ``` **macOS:** ``` ~/Library/Application Support/Claude/claude_desktop_config.json ``` **Linux:** ``` ~/.config/Claude/claude_desktop_config.json ``` ### 2. Add MCP Server Configuration Add the following configuration to your `claude_desktop_config.json`: ```json { "mcpServers": { "ssh-session-manager": { "command": "uv", "args": [ "--directory", "path/to/ssh_mcp", "run", "python", "main.py" ], "env": { "PYTHONPATH": "path/to/ssh_mcp" } } } } ``` **Note:** Replace `path/to/ssh_mcp` with the actual path to your project directory. ### 3. Restart Claude Desktop After saving the configuration, restart Claude Desktop to load the MCP server. ## Available Tools ### `ssh_connect` Create a new SSH connection session. **Parameters:** - `host` (string): SSH server hostname or IP address - `username` (string): SSH username - `password` (string): SSH password - `port` (int, optional): SSH port (default: 22) - `session_name` (string, optional): Custom session name **Example:** ``` Connect to my server using ssh_connect with host="192.168.1.100", username="admin", password="mypassword" ``` ### `ssh_execute` Execute a command in an existing SSH session. **Parameters:** - `session_id` (string): ID of the SSH session - `command` (string): Command to execute - `timeout` (int, optional): Command timeout in seconds (default: 30) **Example:** ``` Execute "ls -la" command in session "ssh_12345678" ``` ### `ssh_list_sessions` List all active SSH sessions. **Example:** ``` Show me all active SSH sessions ``` ### `ssh_session_info` Get detailed information about a specific SSH session. **Parameters:** - `session_id` (string): ID of the SSH session **Example:** ``` Get information about session "ssh_12345678" ``` ### `ssh_close_session` Close a specific SSH session. **Parameters:** - `session_id` (string): ID of the SSH session to close **Example:** ``` Close SSH session "ssh_12345678" ``` ### `ssh_close_all_sessions` Close all active SSH sessions. **Example:** ``` Close all SSH sessions ``` ## Configuration Options ### Session Manager Settings You can modify the session manager settings in `main.py`: ```python ssh_manager = SSHSessionManager( max_sessions=5, # Maximum number of concurrent sessions session_timeout=600 # Session timeout in seconds (10 minutes) ) ``` ### Security Considerations - **Host Key Verification**: Currently disabled for development. Enable proper host key verification for production use. - **Password Storage**: Passwords are not stored persistently but remain in memory during the session. - **Network Security**: Use this tool only on trusted networks. ## Usage Examples ### Basic SSH Connection ``` Connect to server 192.168.1.100 with username "admin" and password "mypass" ``` ### Execute Multiple Commands ``` 1. Connect to my server at example.com with username "user" and password "pass" 2. Execute "whoami" command 3. Execute "df -h" command 4. Show session information ``` ### Session Management ``` 1. List all active sessions 2. Close session with oldest connection 3. Show remaining sessions ``` ## Dependencies - `asyncssh>=2.21.0`: Asynchronous SSH client library - `mcp[cli]>=1.9.2`: Model Context Protocol framework - `paramiko>=3.5.1`: SSH client library (backup/compatibility) ## Development ### Project Structure ``` ssh_mcp/ ├── main.py # Main MCP server implementation ├── pyproject.toml # Project configuration and dependencies ├── uv.lock # Dependency lock file ├── README.md # This file └── run_mcp.bat # Windows batch script for easy execution ``` ### Running in Development Mode ```bash # Run the MCP server directly uv run python main.py # Or use the batch script (Windows) run_mcp.bat ``` ### Adding New Features 1. Modify the `SSHSessionManager` class in `main.py` 2. Add new MCP tools using the `@mcp.tool()` decorator 3. Update this README with new tool documentation ## Troubleshooting ### Connection Issues - Verify SSH server is accessible and credentials are correct - Check firewall settings and network connectivity - Ensure SSH service is running on the target server ### Claude Desktop Integration - Confirm UV is installed and accessible from system PATH - Verify the project path in the configuration is correct - Check Claude Desktop logs for error messages - Restart Claude Desktop after configuration changes ### Session Timeouts - Increase `session_timeout` value in the session manager - Check network stability for long-running sessions - Monitor session activity with `ssh_list_sessions` ## License This project is open source. Please refer to the license file for more information. ## Contributing Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests. ## Changelog ### v0.1.0 - Initial release - Multi-session SSH management - Basic command execution - Session monitoring and cleanup - Claude Desktop integration