🖥️ MCP Terminal Server

Interactive terminal sessions via Model Context Protocol (MCP)

MCP Terminal Server provides cross-platform PTY (pseudo-terminal) support for Windows, Linux, and macOS, exposing terminal sessions through both REST API and MCP protocol. Perfect for AI assistants, remote terminal access, and terminal automation.

✨ Features

🌍 Cross-platform: Works on Windows (cmd.exe/PowerShell), Linux, and macOS
🔄 Real PTY: Supports interactive commands (vim, nano, htop, etc.)
👁️ Visual Snapshots: Captures what a human would see on the terminal screen
🔤 UTF-8 Support: Handles special characters and emojis correctly
🚀 MCP Protocol: Auto-exposes all endpoints as MCP tools via fastapi-mcp
📡 REST API: Full HTTP/REST API with FastAPI
🎯 Multiple Sessions: Manage multiple terminal sessions simultaneously

📦 Installation

From PyPI

pip install mcp-terminal

From Source

git clone https://github.com/alejoair/mcp-terminal
cd mcp-terminal
pip install -e .

🚀 Quick Start

Start the Server

# Start on default port (8777)
mcp-terminal

# Start on custom port
mcp-terminal --port 9000

# Development mode with auto-reload
mcp-terminal --reload

# Custom host and port
mcp-terminal --host 0.0.0.0 --port 8888

Access the Server

Once running, you can access:

API Documentation: http://localhost:8777/docs
MCP Endpoint: http://localhost:8777/mcp
Health Check: http://localhost:8777/health

📖 Usage

REST API

Create a Terminal

curl -X POST http://localhost:8777/terminals \
  -H "Content-Type: application/json" \
  -d '{"rows": 24, "cols": 80}'

Response:

{
  "success": true,
  "terminal_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Terminal created successfully"
}

Send Commands

curl -X POST http://localhost:8777/terminals/{terminal_id}/input \
  -H "Content-Type: application/json" \
  -d '{"data": "echo Hello World\n"}'

Get Visual Snapshot

curl http://localhost:8777/terminals/{terminal_id}/snapshot

Response:

{
  "terminal_id": "550e8400-e29b-41d4-a716-446655440000",
  "display": "C:\\Users\\...\nHello World\nC:\\Users\\...> ",
  "lines": ["C:\\Users\\...", "Hello World", "C:\\Users\\...> "],
  "cursor": {"row": 2, "col": 15},
  "size": {"rows": 24, "cols": 80},
  "is_alive": true,
  "created_at": "2024-01-01T00:00:00"
}

List Terminals

curl http://localhost:8777/terminals

Resize Terminal

curl -X PUT http://localhost:8777/terminals/{terminal_id}/resize \
  -H "Content-Type: application/json" \
  -d '{"rows": 30, "cols": 100}'

Close Terminal

curl -X DELETE http://localhost:8777/terminals/{terminal_id}

MCP Tools

When using with MCP clients (like Claude Desktop), the following tools are automatically available:

create_terminal_terminals__post - Create new terminal
list_terminals_terminals__get - List active terminals
get_terminal_snapshot_terminals__terminal_id__snapshot_get - Get visual snapshot
send_terminal_input_terminals__terminal_id__input_post - Send commands
resize_terminal_terminals__terminal_id__resize_put - Resize terminal
close_terminal_terminals__terminal_id__delete - Close terminal

Python API

from mcp_terminal import TerminalManager

# Create manager
manager = TerminalManager()

# Create terminal
terminal_id = await manager.create(rows=24, cols=80)

# Send input
await manager.send_input(terminal_id, "echo Hello\n")

# Get snapshot
snapshot = await manager.get_snapshot(terminal_id)
print(snapshot["display"])

# Close terminal
await manager.close(terminal_id)

🏗️ Architecture

src/mcp_terminal/
├── __init__.py          # Package initialization
├── __main__.py          # CLI entry point
├── server.py            # FastAPI application with MCP integration
├── core/
│   └── terminal/
│       ├── session.py   # TerminalSession - PTY management
│       ├── buffer.py    # TerminalBuffer - Visual screen capture
│       └── manager.py   # TerminalManager - Multi-session coordinator
└── models/
    └── terminal.py      # Pydantic models for API

🔧 Configuration

Command Line Options

--host HOST          Host to bind to (default: 127.0.0.1)
--port PORT          Port to bind to (default: 8777)
--reload             Enable auto-reload for development
--log-level LEVEL    Set log level (debug, info, warning, error, critical)
--version            Show version and exit

Environment Variables

You can also configure via environment variables:

export MCP_TERMINAL_HOST=0.0.0.0
export MCP_TERMINAL_PORT=9000
export MCP_TERMINAL_LOG_LEVEL=debug

🧪 Testing

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=mcp_terminal

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with FastAPI
Uses terminado for cross-platform PTY support
Uses pyte for terminal emulation
MCP integration via fastapi-mcp

📚 Resources

🐛 Bug Reports

If you find a bug, please open an issue on GitHub.

💬 Support

For questions and support, please use GitHub Discussions.

Made with ❤️ by the MCP Terminal team

mcp-terminal