Terminal MCP Server

Model Context Protocol server for terminal session management, SSH operations, tmux integration, and file operations.

Features

• Session Management: Create, list, manage terminal sessions
• SSH Operations: Execute commands, test connections, manage SSH pool
• Tmux Integration: List and manage tmux sessions
• File Operations: List, upload, download files via SCP
• PTY Operations: Create and manage PTY sessions

Installation

bun install

Usage

Start the MCP Server

# Default port 8913
bun run mcp

# Custom port
MCP_PORT=8914 bun run mcp

# Dev mode (with port 8913)
bun run mcp-dev

Available Tools

Session Management

| Tool | Description | Arguments | |------|-------------|------------| | list_sessions | List all active terminal sessions | none | | get_session_info | Get detailed info about a session | session_id | | create_session | Create a new terminal session | host, type?, command? | | write_command | Write a command to a session | session_id, command | | resize_session | Resize a session terminal | session_id, rows, cols | | close_session | Close a terminal session | session_id |

SSH Operations

| Tool | Description | Arguments | |------|-------------|------------| | exec_ssh | Execute command via SSH | host, command, options? | | test_connection | Test SSH connection | host |

Tmux Operations

| Tool | Description | Arguments | |------|-------------|------------| | list_tmux_sessions | List all tmux sessions | none |

File Operations

| Tool | Description | Arguments | |------|-------------|------------| | list_files | List files on remote host | host, path? | | upload_file | Upload file via SCP | host, local_path, remote_path | | download_file | Download file via SCP | host, remote_path, local_path |

Connection Management

| Tool | Description | Arguments | |------|-------------|------------| | get_active_connections | Get active SSH connections | none |

API Endpoints

Health Check

curl http://localhost:8913/health

Response:

{
  "status": "ok",
  "port": 8913,
  "service": "terminal-mcp"
}

List Available Tools

curl http://localhost:8913/mcp

Execute Tool

curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "list_sessions",
    "args": {}
  }'

Examples

List All Sessions

curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "list_sessions"}'

Create SSH Session

curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "create_session",
    "args": {
      "host": "[email protected]",
      "type": "ssh"
    }
  }'

Execute SSH Command

curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "exec_ssh",
    "args": {
      "host": "[email protected]",
      "command": "ls -la"
    }
  }'

List Tmux Sessions

curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "list_tmux_sessions"}'

Upload File

curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "upload_file",
    "args": {
      "host": "[email protected]",
      "local_path": "/local/file.txt",
      "remote_path": "/remote/file.txt"
    }
  }'

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MCP_PORT | Port for MCP HTTP server | 8913 | | SSH_KEY_PATH | Path to SSH private key | ~/.ssh/id_rsa | | SSH_TIMEOUT | SSH connection timeout (ms) | 30000 | | TMUX_SOCKET_PATH | Custom tmux socket path | (system default) | | DEBUG_TERMINAL_MCP | Enable debug logging | false |

Common Workflows

SSH Connection Testing

# Test if a host is reachable
curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "test_connection",
    "args": {
      "host": "[email protected]"
    }
  }'

Response:

{
  "success": true,
  "host": "[email protected]",
  "message": "Connection successful"
}

Creating and Managing Sessions

# 1. Create a session
curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "create_session",
    "args": {
      "host": "[email protected]",
      "type": "ssh",
      "command": "bash"
    }
  }'

# Response includes session_id

# 2. Write commands to the session
curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "write_command",
    "args": {
      "session_id": "abc123",
      "command": "ls -la /var/log"
    }
  }'

# 3. Close session when done
curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "close_session",
    "args": {
      "session_id": "abc123"
    }
  }'

Parallel SSH Execution

Execute commands on multiple hosts simultaneously:

curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "exec_ssh_parallel",
    "args": {
      "hosts": ["web1.example.com", "web2.example.com", "web3.example.com"],
      "command": "systemctl status nginx"
    }
  }'

File Transfer Operations

# Upload a configuration file
curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "upload_file",
    "args": {
      "host": "[email protected]",
      "local_path": "./nginx.conf",
      "remote_path": "/etc/nginx/nginx.conf"
    }
  }'

# Download log files
curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "download_file",
    "args": {
      "host": "[email protected]",
      "remote_path": "/var/log/app/error.log",
      "local_path": "./error.log"
    }
  }'

Tmux Session Management

# List all tmux sessions on a remote host
curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "list_tmux_sessions",
    "args": {
      "host": "[email protected]"
    }
  }'

# Create a new tmux session
curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "create_tmux_session",
    "args": {
      "host": "[email protected]",
      "session_name": "my-app"
    }
  }'

# Send command to tmux pane
curl -X POST http://localhost:8913/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "send_to_tmux_pane",
    "args": {
      "host": "[email protected]",
      "session_name": "my-app",
      "command": "npm run dev"
    }
  }'

Error Handling

All tools return structured error responses:

{
  "success": false,
  "error": {
    "code": "SSH_CONNECTION_FAILED",
    "message": "Failed to connect to host",
    "details": "Connection refused"
  }
}

Common error codes:

• SSH_CONNECTION_FAILED: Could not establish SSH connection
• SESSION_NOT_FOUND: Requested session does not exist
• INVALID_ARGUMENTS: Missing or invalid arguments
• COMMAND_FAILED: Command execution failed
• FILE_TRANSFER_FAILED: SCP operation failed

Integration with Claude

This MCP server can be integrated with Claude Code or other MCP-compatible clients to provide terminal management capabilities.

Claude Desktop Configuration

{
  "mcpServers": {
    "terminal": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-terminal/src/index.ts"],
      "env": {
        "MCP_PORT": "8913",
        "DEBUG_TERMINAL_MCP": "false"
      }
    }
  }
}

Dependencies

• node-ssh: SSH client functionality
• hono: HTTP server framework
• zod: Schema validation

License

MIT