Planned integration for personal password manager functionality, allowing secure credential storage and retrieval for SSH connections
Planned integration for secure credential storage and retrieval, enabling enterprise-grade secret management for SSH authentication
Planned integration for personal password manager functionality, allowing secure credential storage and retrieval for SSH connections
Planned integration with HashiCorp Vault for multi-cloud secret management and secure credential storage for SSH operations
Provides remote Linux server management capabilities including command execution, system administration, service management, and system monitoring via SSH
Uses macOS Keychain for secure credential storage with TouchID/password protection for SSH authentication
Enables running Puppet agent in no-op mode for configuration management and infrastructure automation on remote systems
SSH MCP Server
An MCP (Model Context Protocol) server that provides SSH client functionality for remote Linux server management. This server enables AI assistants to execute commands on remote Linux hosts via SSH, solving the limitations of built-in tools when working with remote systems.
Why SSH MCP Server?
Built-in MCP tools are limited to local operations. This server extends AI capabilities to remote Linux systems by providing:
Remote Command Execution: Execute any command on remote Linux hosts
System Administration: Manage services, check system health, monitor processes
Secure Authentication: Multiple secure credential storage options
Enterprise Integration: Works with domain-joined systems and enterprise environments
Features
SSH Command Execution: Execute arbitrary commands on remote Linux hosts
Sudo Support: Run commands with elevated privileges (secure password handling)
Installation
From PyPI (Recommended)
From Source
System Information: Get system stats, processes, disk usage, and services
Secure Credentials: Secure credential storage (currently macOS Keychain, expanding to other providers)
Connection Management: Automatic connection handling with timeouts
Error Handling: Comprehensive error reporting and recovery
Puppet Integration: Run Puppet agent in no-op mode for configuration management
Installation
From PyPI (when published)
From Source
Development Installation
Configuration
MCP Client Configuration
Add to your MCP client configuration (e.g., Claude Desktop, Q CLI):
Available Tools
Core SSH Operations
execute_ssh(hostname: str, command: str)
Execute a command on a remote Linux host via SSH.
Parameters:
hostname
: Target hostname (e.g., "server.company.local")command
: Command to execute
Returns:
Or on error:
execute_sudo(hostname: str, command: str)
Execute a command with sudo privileges. Automatically handles password input securely.
Returns: Same format as execute_ssh
System Information Tools
ssh_get_system_info(hostname: str)
Get basic system information (OS, kernel, memory, root disk usage).
get_running_processes(hostname: str)
Get top 10 CPU-consuming processes.
get_disk_usage(hostname: str)
Get disk usage for all mounted filesystems.
get_services(hostname: str)
Get top 20 running systemd services.
ssh_puppet_noop(hostname: str)
Run Puppet agent in no-op mode (dry run) with verbose output.
Usage Examples
Basic Command Execution
System Administration
Error Handling
Security Considerations
Credential Storage: Uses secure credential storage (Keychain, future: Vault, AWS Secrets Manager)
Network Security: Ensure SSH connections are over secure networks
Access Control: Limit SSH user permissions on target hosts
Audit Logging: Monitor SSH access and command execution
TouchID Protection: macOS Keychain integration requires TouchID/password for access
Password Security: Sudo passwords are passed securely via stdin, not visible in process lists
Development
Running Tests
Code Formatting
Type Checking
Coverage Report
Contributing
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature
)Make your changes
Add tests for new functionality
Ensure all tests pass (
pytest
)Format code (
black
andisort
)Commit changes (
git commit -m 'Add amazing feature'
)Push to branch (
git push origin feature/amazing-feature
)Open a Pull Request
Roadmap
SSH key-based authentication
AWS Secrets Manager credential provider
HashiCorp Vault credential provider
Azure Key Vault credential provider
Connection pooling and reuse
File transfer operations (SCP/SFTP)
Interactive shell sessions
Connection health monitoring
Batch command execution
Custom SSH client configuration
Windows support (additional credential providers)
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
Issues: GitHub Issues
Discussions: GitHub Discussions
Changelog: CHANGELOG.md
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables AI assistants to execute commands an