| Name | ssh-mcp-py JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | A Model Context Protocol for managing and interacting with multiple virtual machines over SSH |
| upload_time | 2025-09-03 10:33:15 |
| maintainer | None |
| docs_url | None |
| author | Sean Dang |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
vm
mcp
llm
automation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SSH MCP: Model Context Protocol tool for Virtual Machine Management over SSH
SSH MCP is a Model Context Protocol tool written in Python for managing and interacting with multiple virtual machines (VMs) over SSH. It simplifies executing commands on remote servers by using the standard SSH config file format and leverages the robust `paramiko` library to handle SSH connections and command execution securely and efficiently.
-----
## Key Features 🚀
- **Standard SSH Config**: Uses the familiar `~/.ssh/config` file format for managing VM connection details
- **Automatic Key Management**: Uses SSH keys specified in the config file for each host
- **Remote Command Execution**: Execute terminal commands on any configured VM directly from your local machine
- **MCP Integration**: Provides tools for AI assistants through the Model Context Protocol
- **Simplified Workflow**: Streamline your server administration tasks using standard SSH configuration
-----
## Requirements 📋
To use SSH MCP, you'll need the following on your system:
- **Python 3.12 or higher**: Ensure you have a recent version of Python installed.
- **paramiko**: The core Python library for the SSHv2 protocol.
- **fastmcp**: For MCP server functionality.
-----
## Installation 💻
1. **Clone the Repository**: Start by cloning the SSH MCP repository to your local machine
2. **Install Dependencies**: Install the necessary Python libraries `uv sync`
-----
## Configuration ⚙️
SSH MCP uses the standard SSH configuration file format. By default, it looks for `~/.ssh/config`, but you can specify a custom path using the `SSH_CONFIG_PATH` environment variable.
### SSH Config File Setup
Create or update your `~/.ssh/config` file with your server details:
**Example `~/.ssh/config`:**
```config
Host web-server-01
HostName 192.168.1.101
Port 22
User admin
IdentityFile ~/.ssh/id_rsa
Host db-server-01
HostName 192.168.1.102
Port 22
User dba
IdentityFile ~/.ssh/id_rsa
Host app-server-01
HostName 192.168.1.103
Port 2222
User deployer
IdentityFile ~/.ssh/id_ed25519
```
### Environment Variables (Optional)
- `SSH_CONFIG_PATH`: Path to SSH config file (defaults to `~/.ssh/config`)
-----
## Usage Guide 📖
SSH MCP can be used in two ways: as a direct command-line tool or as an MCP (Model Context Protocol) server.
### Direct Command-Line Usage
You can execute commands directly using the command line interface:
**Basic Command Execution**:
```bash
python cli.py <host> "<command_to_execute>"
```
**Examples**:
To list the files in the home directory of `web-server-01`:
```bash
python cli.py web-server-01 "ls -l /home/admin"
```
To check the disk space on `db-server-01`:
```bash
python cli.py db-server-01 "df -h"
```
### MCP Server Usage
SSH MCP can also run as an MCP server, providing tools that can be used by AI assistants and other MCP clients:
```bash
python main.py
```
**Available MCP Tools:**
1. **execute_ssh_command**: Execute a command on a remote host
- Parameters: `hostname` (string), `command` (string)
2. **list_ssh_hosts**: List all configured SSH hosts
- Parameters: None
3. **get_host_info**: Get detailed information about a specific host
- Parameters: `hostname` (string)
4. **test_ssh_connection**: Test SSH connection to a host
- Parameters: `hostname` (string)
-----
## Architecture & Workflow 🏗️
SSH MCP follows a clean architecture with clear separation between configuration management, SSH operations, and MCP integration.
### Class Structure
```mermaid
classDiagram
class SSHConfig {
+config_file_path: str
+ssh_config: paramiko.SSHConfig
+__init__()
+_load_ssh_config() paramiko.SSHConfig
+get_host_config(hostname) Dict
+list_hosts() List[str]
}
class SSHClient {
+config: SSHConfig
+__init__(config)
+execute_command(hostname, command) Dict
+list_hosts() List[str]
}
class MCPTools {
+execute_ssh_command(hostname, command) str
+list_ssh_hosts() str
+get_host_info(hostname) str
+test_ssh_connection(hostname) str
}
SSHClient --> SSHConfig : uses
MCPTools --> SSHClient : uses
SSHConfig --> paramiko.SSHConfig : wraps
```
### Workflow Diagram
```mermaid
graph TD
A[MCP Client Request] --> B{Tool Type}
B -->|execute_ssh_command| C[execute_ssh_command]
B -->|list_ssh_hosts| D[list_ssh_hosts]
B -->|get_host_info| E[get_host_info]
B -->|test_ssh_connection| F[test_ssh_connection]
C --> G[get_ssh_client]
D --> G
E --> G
F --> G
G --> H[SSHClient.__init__]
H --> I[SSHConfig.__init__]
I --> J[_load_ssh_config]
J --> K[paramiko.SSHConfig.parse]
C --> L[SSHClient.execute_command]
L --> M[get_host_config]
M --> N[paramiko.SSHConfig.lookup]
N --> O[paramiko.SSHClient.connect]
O --> P[paramiko.SSHClient.exec_command]
D --> Q[SSHConfig.list_hosts]
Q --> R[paramiko.SSHConfig.get_hostnames]
E --> M
F --> M
F --> S[paramiko.SSHClient.connect]
```
-----
## Development & Testing 🧪
SSH MCP uses a focused testing approach that emphasizes real integration tests over complex mocked unit tests.
### Test Structure
- **`tests/test_ssh_client.py`**: Basic unit tests for core functionality
- **`tests/test_mcp.py`**: Minimal MCP tool tests with simple mocking
- **`tests/test_integration.py`**: Real integration tests that connect to actual SSH hosts
## Development Guide 🛠️
### Pre-commit Setup (Highly Recommended)
**Before starting development**, it's highly recommended to install pre-commit hooks to ensure code quality:
```bash
# Install pre-commit hooks (run this first!)
uv run pre-commit install
```
This will automatically run code quality checks before each commit, catching issues early and maintaining consistent code standards.
### Integration Testing Setup
The integration tests require a host named `test` in your SSH config. Add a host like this to `~/.ssh/config`:
```config
Host test
HostName your-test-server.com
User your-username
IdentityFile ~/.ssh/your-key
```
The integration tests will:
- Connect to the real SSH host
- Execute actual Linux commands
- Test the full MCP workflow end-to-end
### Running Tests
```bash
# Run all tests
uv run pytest tests/ -v
# Run only integration tests (requires 'test' host)
uv run pytest tests/test_integration.py -v
# Run only unit tests
uv run pytest tests/test_ssh_client.py tests/test_mcp.py -v
# Run with coverage
uv run pytest tests/ --cov=ssh_mcp --cov-report=html
```
### Code Quality
The project uses `ruff` for linting and formatting:
```bash
# Check code quality
uv run ruff check .
# Format code
uv run ruff format .
```
### Publishing to PyPI
To publish this package to PyPI:
```bash
# Build the package
uv build
# Publish to PyPI (requires API token)
uv publish --username __token__ --password YOUR_PYPI_API_KEY
```
Replace `YOUR_PYPI_API_KEY` with your actual PyPI API token.
Raw data
{
"_id": null,
"home_page": null,
"name": "ssh-mcp-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Sean Dang <sondt.2709@gmail.com>",
"keywords": "vm, mcp, llm, automation",
"author": "Sean Dang",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/42/54/2866ee99fbdc91b93c4c12bc5690c68cff7ab926b770a521f037ceebed22/ssh_mcp_py-0.1.1.tar.gz",
"platform": null,
"description": "# SSH MCP: Model Context Protocol tool for Virtual Machine Management over SSH\n\nSSH MCP is a Model Context Protocol tool written in Python for managing and interacting with multiple virtual machines (VMs) over SSH. It simplifies executing commands on remote servers by using the standard SSH config file format and leverages the robust `paramiko` library to handle SSH connections and command execution securely and efficiently.\n\n-----\n\n## Key Features \ud83d\ude80\n\n- **Standard SSH Config**: Uses the familiar `~/.ssh/config` file format for managing VM connection details\n- **Automatic Key Management**: Uses SSH keys specified in the config file for each host\n- **Remote Command Execution**: Execute terminal commands on any configured VM directly from your local machine\n- **MCP Integration**: Provides tools for AI assistants through the Model Context Protocol\n- **Simplified Workflow**: Streamline your server administration tasks using standard SSH configuration\n\n-----\n\n## Requirements \ud83d\udccb\n\nTo use SSH MCP, you'll need the following on your system:\n\n- **Python 3.12 or higher**: Ensure you have a recent version of Python installed.\n- **paramiko**: The core Python library for the SSHv2 protocol.\n- **fastmcp**: For MCP server functionality.\n\n-----\n\n## Installation \ud83d\udcbb\n\n1. **Clone the Repository**: Start by cloning the SSH MCP repository to your local machine\n2. **Install Dependencies**: Install the necessary Python libraries `uv sync`\n\n-----\n\n## Configuration \u2699\ufe0f\n\nSSH MCP uses the standard SSH configuration file format. By default, it looks for `~/.ssh/config`, but you can specify a custom path using the `SSH_CONFIG_PATH` environment variable.\n\n### SSH Config File Setup\n\nCreate or update your `~/.ssh/config` file with your server details:\n\n**Example `~/.ssh/config`:**\n\n```config\nHost web-server-01\n HostName 192.168.1.101\n Port 22\n User admin\n IdentityFile ~/.ssh/id_rsa\n\nHost db-server-01\n HostName 192.168.1.102\n Port 22\n User dba\n IdentityFile ~/.ssh/id_rsa\n\nHost app-server-01\n HostName 192.168.1.103\n Port 2222\n User deployer\n IdentityFile ~/.ssh/id_ed25519\n```\n\n### Environment Variables (Optional)\n\n- `SSH_CONFIG_PATH`: Path to SSH config file (defaults to `~/.ssh/config`)\n\n-----\n\n## Usage Guide \ud83d\udcd6\n\nSSH MCP can be used in two ways: as a direct command-line tool or as an MCP (Model Context Protocol) server.\n\n### Direct Command-Line Usage\n\nYou can execute commands directly using the command line interface:\n\n**Basic Command Execution**:\n\n```bash\npython cli.py <host> \"<command_to_execute>\"\n```\n\n**Examples**:\n\nTo list the files in the home directory of `web-server-01`:\n\n```bash\npython cli.py web-server-01 \"ls -l /home/admin\"\n```\n\nTo check the disk space on `db-server-01`:\n\n```bash\npython cli.py db-server-01 \"df -h\"\n```\n\n### MCP Server Usage\n\nSSH MCP can also run as an MCP server, providing tools that can be used by AI assistants and other MCP clients:\n\n```bash\npython main.py\n```\n\n**Available MCP Tools:**\n\n1. **execute_ssh_command**: Execute a command on a remote host\n - Parameters: `hostname` (string), `command` (string)\n\n2. **list_ssh_hosts**: List all configured SSH hosts\n - Parameters: None\n\n3. **get_host_info**: Get detailed information about a specific host\n - Parameters: `hostname` (string)\n\n4. **test_ssh_connection**: Test SSH connection to a host\n - Parameters: `hostname` (string)\n\n-----\n\n## Architecture & Workflow \ud83c\udfd7\ufe0f\n\nSSH MCP follows a clean architecture with clear separation between configuration management, SSH operations, and MCP integration.\n\n### Class Structure\n\n```mermaid\nclassDiagram\n class SSHConfig {\n +config_file_path: str\n +ssh_config: paramiko.SSHConfig\n +__init__()\n +_load_ssh_config() paramiko.SSHConfig\n +get_host_config(hostname) Dict\n +list_hosts() List[str]\n }\n \n class SSHClient {\n +config: SSHConfig\n +__init__(config)\n +execute_command(hostname, command) Dict\n +list_hosts() List[str]\n }\n \n class MCPTools {\n +execute_ssh_command(hostname, command) str\n +list_ssh_hosts() str\n +get_host_info(hostname) str\n +test_ssh_connection(hostname) str\n }\n \n SSHClient --> SSHConfig : uses\n MCPTools --> SSHClient : uses\n SSHConfig --> paramiko.SSHConfig : wraps\n```\n\n### Workflow Diagram\n\n```mermaid\ngraph TD\n A[MCP Client Request] --> B{Tool Type}\n B -->|execute_ssh_command| C[execute_ssh_command]\n B -->|list_ssh_hosts| D[list_ssh_hosts]\n B -->|get_host_info| E[get_host_info]\n B -->|test_ssh_connection| F[test_ssh_connection]\n \n C --> G[get_ssh_client]\n D --> G\n E --> G\n F --> G\n \n G --> H[SSHClient.__init__]\n H --> I[SSHConfig.__init__]\n I --> J[_load_ssh_config]\n J --> K[paramiko.SSHConfig.parse]\n \n C --> L[SSHClient.execute_command]\n L --> M[get_host_config]\n M --> N[paramiko.SSHConfig.lookup]\n N --> O[paramiko.SSHClient.connect]\n O --> P[paramiko.SSHClient.exec_command]\n \n D --> Q[SSHConfig.list_hosts]\n Q --> R[paramiko.SSHConfig.get_hostnames]\n \n E --> M\n F --> M\n F --> S[paramiko.SSHClient.connect]\n```\n\n-----\n\n## Development & Testing \ud83e\uddea\n\nSSH MCP uses a focused testing approach that emphasizes real integration tests over complex mocked unit tests.\n\n### Test Structure\n\n- **`tests/test_ssh_client.py`**: Basic unit tests for core functionality\n- **`tests/test_mcp.py`**: Minimal MCP tool tests with simple mocking\n- **`tests/test_integration.py`**: Real integration tests that connect to actual SSH hosts\n\n## Development Guide \ud83d\udee0\ufe0f\n\n### Pre-commit Setup (Highly Recommended)\n\n**Before starting development**, it's highly recommended to install pre-commit hooks to ensure code quality:\n\n```bash\n# Install pre-commit hooks (run this first!)\nuv run pre-commit install\n```\n\nThis will automatically run code quality checks before each commit, catching issues early and maintaining consistent code standards.\n\n### Integration Testing Setup\n\nThe integration tests require a host named `test` in your SSH config. Add a host like this to `~/.ssh/config`:\n\n```config\nHost test\n HostName your-test-server.com\n User your-username\n IdentityFile ~/.ssh/your-key\n```\n\nThe integration tests will:\n\n- Connect to the real SSH host\n- Execute actual Linux commands\n- Test the full MCP workflow end-to-end\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest tests/ -v\n\n# Run only integration tests (requires 'test' host)\nuv run pytest tests/test_integration.py -v\n\n# Run only unit tests\nuv run pytest tests/test_ssh_client.py tests/test_mcp.py -v\n\n# Run with coverage\nuv run pytest tests/ --cov=ssh_mcp --cov-report=html\n```\n\n### Code Quality\n\nThe project uses `ruff` for linting and formatting:\n\n```bash\n# Check code quality\nuv run ruff check .\n\n# Format code\nuv run ruff format .\n```\n\n### Publishing to PyPI\n\nTo publish this package to PyPI:\n\n```bash\n# Build the package\nuv build\n\n# Publish to PyPI (requires API token)\nuv publish --username __token__ --password YOUR_PYPI_API_KEY\n```\n\nReplace `YOUR_PYPI_API_KEY` with your actual PyPI API token.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Model Context Protocol for managing and interacting with multiple virtual machines over SSH",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/sondt2709/ssh-mcp-py",
"Repository": "https://github.com/sondt2709/ssh-mcp-py"
},
"split_keywords": [
"vm",
" mcp",
" llm",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "56abbac58ac57a7ee1dd79516c5445814aef585fab61d713e5d1b40f666a7e19",
"md5": "da9ecfa2a0a83db56aaed69113ef5a7c",
"sha256": "f71e9483454e178c165fa318dde60fdc2390cc6c9610f3e8af7fe2480e5ef3dc"
},
"downloads": -1,
"filename": "ssh_mcp_py-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "da9ecfa2a0a83db56aaed69113ef5a7c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7235,
"upload_time": "2025-09-03T10:33:14",
"upload_time_iso_8601": "2025-09-03T10:33:14.721265Z",
"url": "https://files.pythonhosted.org/packages/56/ab/bac58ac57a7ee1dd79516c5445814aef585fab61d713e5d1b40f666a7e19/ssh_mcp_py-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "42542866ee99fbdc91b93c4c12bc5690c68cff7ab926b770a521f037ceebed22",
"md5": "13d78d79ffe73099a9758d99f2f9009e",
"sha256": "19af75c7f6a1c4d810c30ef6b2dc9e7d286c538c9cd52fc46a8e99c294d85b5f"
},
"downloads": -1,
"filename": "ssh_mcp_py-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "13d78d79ffe73099a9758d99f2f9009e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 8257,
"upload_time": "2025-09-03T10:33:15",
"upload_time_iso_8601": "2025-09-03T10:33:15.988573Z",
"url": "https://files.pythonhosted.org/packages/42/54/2866ee99fbdc91b93c4c12bc5690c68cff7ab926b770a521f037ceebed22/ssh_mcp_py-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 10:33:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sondt2709",
"github_project": "ssh-mcp-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ssh-mcp-py"
}
