| Name | mcp-ssh-session JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | MCP server for managing persistent SSH sessions |
| upload_time | 2025-10-30 04:30:41 |
| maintainer | None |
| docs_url | None |
| author | Jon |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2024 Jon
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
cli
fastmcp
mcp
ssh
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MCP SSH Session
An MCP (Model Context Protocol) server that enables AI agents to establish and manage persistent SSH sessions.
## Features
- **Persistent Sessions**: SSH connections are reused across multiple command executions
- **SSH Config Support**: Automatically reads and uses settings from `~/.ssh/config`
- **Multi-host Support**: Manage connections to multiple hosts simultaneously
- **Automatic Reconnection**: Dead connections are detected and automatically re-established
- **Thread-safe**: Safe for concurrent operations
- **Network Device Support**: Automatic enable mode handling for routers and switches
- **Sudo Support**: Automatic password handling for sudo commands on Unix/Linux hosts
- **File Operations**: Safe helpers to read and write remote files over SFTP
## Installation
### Using `uvx`
```bash
uvx mcp-ssh-session
```
### Using Claude Code
Add to your `~/.claude.json`:
```json
{
"mcpServers": {
"ssh-session": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-ssh-session"],
"env": {}
}
}
}
```
### Using MCP Inspector
```bash
npx @modelcontextprotocol/inspector uvx mcp-ssh-session
```
### Development Installation
```bash
uv venv
source .venv/bin/activate
uv pip install -e .
```
## Usage
### Available Tools
#### `execute_command`
Execute a command on an SSH host using a persistent session.
**Using SSH config alias:**
```json
{
"host": "myserver",
"command": "uptime"
}
```
**Using explicit parameters:**
```json
{
"host": "example.com",
"username": "user",
"command": "ls -la",
"key_filename": "~/.ssh/id_rsa",
"port": 22
}
```
**Network device with enable mode:**
```json
{
"host": "router.example.com",
"username": "admin",
"password": "ssh_password",
"enable_password": "enable_password",
"command": "show running-config"
}
```
**Unix/Linux with sudo:**
```json
{
"host": "server.example.com",
"username": "user",
"sudo_password": "user_password",
"command": "systemctl restart nginx"
}
```
#### `list_sessions`
List all active SSH sessions.
#### `close_session`
Close a specific SSH session.
```json
{
"host": "myserver"
}
```
#### `close_all_sessions`
Close all active SSH sessions.
#### `read_file`
Read the contents of a remote file via SFTP.
```json
{
"host": "myserver",
"remote_path": "/etc/nginx/nginx.conf",
"max_bytes": 131072
}
```
- Uses persistent SSH sessions and opens short-lived SFTP channels
- Enforces a 2 MB maximum per request (configurable per call up to that limit)
- Returns truncated notice when the content size exceeds the requested limit
#### `write_file`
Write text content to a remote file via SFTP.
```json
{
"host": "myserver",
"remote_path": "/tmp/app.env",
"content": "DEBUG=true\n",
"append": true,
"make_dirs": true
}
```
- Content larger than 2 MB is rejected for safety
- Optional `append` mode to add to existing files
- Optional `make_dirs` flag will create missing parent directories
- Supports `permissions` to set octal file modes after write (e.g., `420` for `0644`)
## SSH Config Support
The server automatically reads `~/.ssh/config` and supports:
- Host aliases
- Hostname mappings
- Port configurations
- User specifications
- IdentityFile settings
Example `~/.ssh/config`:
```
Host myserver
HostName example.com
User myuser
Port 2222
IdentityFile ~/.ssh/id_rsa
```
Then simply use:
```json
{
"host": "myserver",
"command": "uptime"
}
```
## Documentation
See [CLAUDE.md](CLAUDE.md) for detailed documentation.
## License
Distributed under the MIT License. See `LICENSE` for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-ssh-session",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cli, fastmcp, mcp, ssh",
"author": "Jon",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f2/1b/0014ac32bc212e4fc69182a4349aa56be514dabd78b6d03e0937151d04f1/mcp_ssh_session-0.1.0.tar.gz",
"platform": null,
"description": "# MCP SSH Session\n\nAn MCP (Model Context Protocol) server that enables AI agents to establish and manage persistent SSH sessions.\n\n## Features\n\n- **Persistent Sessions**: SSH connections are reused across multiple command executions\n- **SSH Config Support**: Automatically reads and uses settings from `~/.ssh/config`\n- **Multi-host Support**: Manage connections to multiple hosts simultaneously\n- **Automatic Reconnection**: Dead connections are detected and automatically re-established\n- **Thread-safe**: Safe for concurrent operations\n- **Network Device Support**: Automatic enable mode handling for routers and switches\n- **Sudo Support**: Automatic password handling for sudo commands on Unix/Linux hosts\n- **File Operations**: Safe helpers to read and write remote files over SFTP\n\n## Installation\n\n### Using `uvx`\n\n```bash\nuvx mcp-ssh-session\n```\n\n### Using Claude Code\n\nAdd to your `~/.claude.json`:\n\n```json\n{\n \"mcpServers\": {\n \"ssh-session\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"mcp-ssh-session\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Using MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector uvx mcp-ssh-session\n```\n\n### Development Installation\n\n```bash\nuv venv\nsource .venv/bin/activate\nuv pip install -e .\n```\n\n## Usage\n\n### Available Tools\n\n#### `execute_command`\nExecute a command on an SSH host using a persistent session.\n\n**Using SSH config alias:**\n```json\n{\n \"host\": \"myserver\",\n \"command\": \"uptime\"\n}\n```\n\n**Using explicit parameters:**\n```json\n{\n \"host\": \"example.com\",\n \"username\": \"user\",\n \"command\": \"ls -la\",\n \"key_filename\": \"~/.ssh/id_rsa\",\n \"port\": 22\n}\n```\n\n**Network device with enable mode:**\n```json\n{\n \"host\": \"router.example.com\",\n \"username\": \"admin\",\n \"password\": \"ssh_password\",\n \"enable_password\": \"enable_password\",\n \"command\": \"show running-config\"\n}\n```\n\n**Unix/Linux with sudo:**\n```json\n{\n \"host\": \"server.example.com\",\n \"username\": \"user\",\n \"sudo_password\": \"user_password\",\n \"command\": \"systemctl restart nginx\"\n}\n```\n\n#### `list_sessions`\nList all active SSH sessions.\n\n#### `close_session`\nClose a specific SSH session.\n\n```json\n{\n \"host\": \"myserver\"\n}\n```\n\n#### `close_all_sessions`\nClose all active SSH sessions.\n\n#### `read_file`\nRead the contents of a remote file via SFTP.\n\n```json\n{\n \"host\": \"myserver\",\n \"remote_path\": \"/etc/nginx/nginx.conf\",\n \"max_bytes\": 131072\n}\n```\n\n- Uses persistent SSH sessions and opens short-lived SFTP channels\n- Enforces a 2 MB maximum per request (configurable per call up to that limit)\n- Returns truncated notice when the content size exceeds the requested limit\n\n#### `write_file`\nWrite text content to a remote file via SFTP.\n\n```json\n{\n \"host\": \"myserver\",\n \"remote_path\": \"/tmp/app.env\",\n \"content\": \"DEBUG=true\\n\",\n \"append\": true,\n \"make_dirs\": true\n}\n```\n\n- Content larger than 2 MB is rejected for safety\n- Optional `append` mode to add to existing files\n- Optional `make_dirs` flag will create missing parent directories\n- Supports `permissions` to set octal file modes after write (e.g., `420` for `0644`)\n\n## SSH Config Support\n\nThe server automatically reads `~/.ssh/config` and supports:\n- Host aliases\n- Hostname mappings\n- Port configurations\n- User specifications\n- IdentityFile settings\n\nExample `~/.ssh/config`:\n```\nHost myserver\n HostName example.com\n User myuser\n Port 2222\n IdentityFile ~/.ssh/id_rsa\n```\n\nThen simply use:\n```json\n{\n \"host\": \"myserver\",\n \"command\": \"uptime\"\n}\n```\n\n## Documentation\n\nSee [CLAUDE.md](CLAUDE.md) for detailed documentation.\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for details.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 Jon\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "MCP server for managing persistent SSH sessions",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/devnullvoid/mcp-ssh-session",
"Issues": "https://github.com/devnullvoid/mcp-ssh-session/issues",
"Repository": "https://github.com/devnullvoid/mcp-ssh-session"
},
"split_keywords": [
"cli",
" fastmcp",
" mcp",
" ssh"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "32a8b6a4a24809c8bc8e38f4ccdf14ca240209c0fa1ad0a00e3db102e5c23d4e",
"md5": "dd27eba34925fd4655097b8265ee2f40",
"sha256": "681fa13373883d70d238b6c332bafc1d3b00cf7b1dd28e4e6db08fcce170943f"
},
"downloads": -1,
"filename": "mcp_ssh_session-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dd27eba34925fd4655097b8265ee2f40",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15240,
"upload_time": "2025-10-30T04:30:39",
"upload_time_iso_8601": "2025-10-30T04:30:39.549490Z",
"url": "https://files.pythonhosted.org/packages/32/a8/b6a4a24809c8bc8e38f4ccdf14ca240209c0fa1ad0a00e3db102e5c23d4e/mcp_ssh_session-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f21b0014ac32bc212e4fc69182a4349aa56be514dabd78b6d03e0937151d04f1",
"md5": "7f441327b9d92e1c31606b1024f3e9c8",
"sha256": "6134a172e3eda8d4135ad44ba0f5e00360d6784ccf30cb2699a6b7eb139ee015"
},
"downloads": -1,
"filename": "mcp_ssh_session-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "7f441327b9d92e1c31606b1024f3e9c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 99471,
"upload_time": "2025-10-30T04:30:41",
"upload_time_iso_8601": "2025-10-30T04:30:41.047301Z",
"url": "https://files.pythonhosted.org/packages/f2/1b/0014ac32bc212e4fc69182a4349aa56be514dabd78b6d03e0937151d04f1/mcp_ssh_session-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 04:30:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "devnullvoid",
"github_project": "mcp-ssh-session",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mcp-ssh-session"
}
