MCP Terminal Server

# 🖥️ MCP Terminal Server [](https://badge.fury.io/py/mcp-terminal) [](https://pypi.org/project/mcp-terminal/) [](https://opensource.org/licenses/MIT) **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 ```bash pip install mcp-terminal ``` ### From Source ```bash git clone https://github.com/alejoair/mcp-terminal cd mcp-terminal pip install -e . ``` ## 🚀 Quick Start ### Start the Server ```bash # 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 ```bash curl -X POST http://localhost:8777/terminals \ -H "Content-Type: application/json" \ -d '{"rows": 24, "cols": 80}' ``` Response: ```json { "success": true, "terminal_id": "550e8400-e29b-41d4-a716-446655440000", "message": "Terminal created successfully" } ``` #### Send Commands ```bash curl -X POST http://localhost:8777/terminals/{terminal_id}/input \ -H "Content-Type: application/json" \ -d '{"data": "echo Hello World\n"}' ``` #### Get Visual Snapshot ```bash curl http://localhost:8777/terminals/{terminal_id}/snapshot ``` Response: ```json { "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 ```bash curl http://localhost:8777/terminals ``` #### Resize Terminal ```bash curl -X PUT http://localhost:8777/terminals/{terminal_id}/resize \ -H "Content-Type: application/json" \ -d '{"rows": 30, "cols": 100}' ``` #### Close Terminal ```bash 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 ```python 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: ```bash export MCP_TERMINAL_HOST=0.0.0.0 export MCP_TERMINAL_PORT=9000 export MCP_TERMINAL_LOG_LEVEL=debug ``` ## 🧪 Testing ```bash # 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. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🙏 Acknowledgments - Built with [FastAPI](https://fastapi.tiangolo.com/) - Uses [terminado](https://github.com/jupyter/terminado) for cross-platform PTY support - Uses [pyte](https://github.com/selectel/pyte) for terminal emulation - MCP integration via [fastapi-mcp](https://github.com/mcp/fastapi-mcp) ## 📚 Resources - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - [FastAPI Documentation](https://fastapi.tiangolo.com/) - [terminado Documentation](https://terminado.readthedocs.io/) ## 🐛 Bug Reports If you find a bug, please open an issue on [GitHub](https://github.com/alejoair/mcp-terminal/issues). ## 💬 Support For questions and support, please use [GitHub Discussions](https://github.com/alejoair/mcp-terminal/discussions). --- Made with ❤️ by the MCP Terminal team