# SSH MCP Server

A Model Context Protocol (MCP) server for managing Linux servers via SSH. This server provides tools for executing commands, managing files, monitoring services, and analyzing logs on remote Linux systems.

## Installation

### Docker (Recommended)

1. Copy the environment file and configure your SSH credentials:
```bash
cp env.example .env
# Edit .env with your SSH server details
```

2. Build and run with Docker Compose:
```bash
docker compose up -d
```

### Manual Installation

1. Install dependencies:
```bash
pip install -r requirements.txt
```

2. Set environment variables:
```bash
export SSH_HOST=your-server.example.com
export SSH_USER=root
export SSH_PASSWORD=your_password
# OR
export SSH_KEY_FILE=/path/to/private/key
```

3. Run the server:
```bash
python -m ssh_mcp_server.server
```
### AnythingLLM Integration

Add the following configuration to your `anythingllm_mcp_servers.json`:

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "name": "SSH MCP Server",
      "type": "streamable",
      "url": "http://ssh-mcp-server:8000/mcp",
      "auth_token": null,
      "enabled": true
    }
  }
}
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SSH_HOST` | Target server hostname or IP | `localhost` |
| `SSH_USER` | SSH username | `root` |
| `SSH_PASSWORD` | SSH password | - |
| `SSH_KEY_FILE` | Path to SSH private key | - |
| `SSH_PORT` | SSH port | `22` |
| `SERVER_HOST` | MCP server bind address | `0.0.0.0` |
| `SERVER_PORT` | MCP server port | `8000` |

### Authentication

The server supports two authentication methods:

1. **Password Authentication**: Set `SSH_PASSWORD` in your environment
2. **Key-based Authentication**: Set `SSH_KEY_FILE` to the path of your private key

## Usage

### Basic Connection Test

```python
# Test SSH connection
test_ssh_connection(
    hostname="server.example.com",
    username="root",
    password="your_password"
)
```

### Execute Commands

```python
# Execute a simple command
execute_command("ls -la /var/log")

# Execute with sudo
execute_command("systemctl status nginx", use_sudo=True)
```

### File Operations

```python
# Read a file
read_file("/etc/nginx/nginx.conf")

# Write to a file
write_file("/tmp/test.txt", "Hello World!")

# List directory contents
list_directory("/var/log")
```

### Service Management

```python
# Check service status
get_service_status("nginx")

# Start a service
start_service("nginx")

# Stop a service
stop_service("nginx")

# Restart a service
restart_service("nginx")
```

### Process Management

```python
# List all processes
list_processes()

# List specific processes
list_processes(filter_by="nginx")

# Kill a process
kill_process("12345", signal="TERM")
```

### Network Tools

```python
# Check if port is open
check_port(80)

# Get network connections
get_network_connections()
```

### Log Analysis

```python
# Tail a log file
tail_log("/var/log/nginx/access.log", lines=100)

# Search in logs
search_log("/var/log/nginx/error.log", "error")
```

## Security Considerations

- Use SSH key-based authentication when possible
- Limit SSH access to specific users and IPs
- Regularly rotate SSH keys and passwords
- Monitor SSH access logs
- Use sudo judiciously and limit sudo privileges

## Troubleshooting

### Connection Issues

1. **Authentication Failed**: Check username, password, or key file
2. **Connection Refused**: Verify SSH service is running and port is correct
3. **Host Key Verification**: Ensure the server's host key is trusted

### Permission Issues

1. **File Access Denied**: Check file permissions and ownership
2. **Sudo Required**: Use `use_sudo=True` for privileged operations
3. **Service Management**: Ensure user has appropriate systemd permissions

### Performance Issues

1. **Slow Commands**: Increase timeout values for long-running commands
2. **Connection Timeouts**: Check network connectivity and server load
3. **Resource Usage**: Monitor server resources during operations

## API Reference

The server exposes the following MCP tools:

- `test_ssh_connection`: Test SSH connectivity
- `get_server_info`: Get system information
- `execute_command`: Execute commands
- `read_file`: Read file contents
- `write_file`: Write file contents
- `list_directory`: List directory contents
- `get_service_status`: Check service status
- `start_service`: Start a service
- `stop_service`: Stop a service
- `restart_service`: Restart a service
- `list_processes`: List running processes
- `kill_process`: Kill a process
- `check_port`: Check port status
- `get_network_connections`: Get network connections
- `tail_log`: Tail log files
- `search_log`: Search log files

## License

This project is licensed under the MIT License.