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"
    }
  }'

Integration with Claude

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

Dependencies

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

License

MIT