Terminally MCP

<div align="center"> # 🖥️ Terminally MCP ### **Supercharge AI Assistants with Terminal Control Powers** ⚡ [](https://modelcontextprotocol.io) [](https://nodejs.org) [](https://www.typescriptlang.org) [](https://opensource.org/licenses/ISC) *Give your AI assistant the power to create, manage, and control terminal sessions like a pro developer! Built on the Model Context Protocol (MCP) for seamless integration with AI tools like Claude, ChatGPT, and more.* [Features](#-features) • [Quick Start](#-quick-start) • [Installation](#-installation) • [API Reference](#-api-reference) • [Examples](#-examples) </div> --- ## 🎯 What is Terminally MCP? Terminally MCP is a **Model Context Protocol (MCP) server** that bridges the gap between AI assistants and terminal operations. It provides a safe, controlled environment where AI can: - 🚀 **Execute shell commands** with full output capture - 📂 **Manage multiple terminal sessions** simultaneously - 🔍 **Read terminal history** and scrollback buffers - 🛡️ **Isolated tmux environment** that won't interfere with your existing sessions - ⚡ **Real-time command execution** with timeout protection Perfect for AI-powered development workflows, automation, system administration, and interactive coding assistance! ## ✨ Features <table> <tr> <td width="50%"> ### 🎮 Terminal Control - Create and manage multiple terminal tabs - Execute commands with proper quote/escape handling - Capture command output and exit codes - Read terminal history and scrollback </td> <td width="50%"> ### 🔒 Safe & Isolated - Dedicated tmux server instance - No interference with user's tmux sessions - Timeout protection for long-running commands - Clean session management </td> </tr> <tr> <td width="50%"> ### 🤖 AI-Optimized - MCP protocol compliance - Structured JSON responses - Error handling and recovery - Marker-based output capture </td> <td width="50%"> ### 🛠️ Developer Friendly - TypeScript with full type safety - Comprehensive test suite - Clean, modular architecture - Easy to extend and customize </td> </tr> </table> ## 🚀 Quick Start Get up and running in under 2 minutes! ```bash # Clone the repository git clone https://github.com/yourusername/terminally-mcp.git cd terminally-mcp # Install dependencies (we recommend pnpm for speed!) pnpm install # Build the TypeScript code pnpm build # Start the MCP server pnpm start ``` That's it! The server is now ready to accept MCP connections. ## 📦 Installation ### Prerequisites - **Node.js** v16 or higher - **tmux** installed on your system - **pnpm** (recommended) or npm/yarn ### Install tmux <details> <summary>🍎 macOS</summary> ```bash brew install tmux ``` </details> <details> <summary>🐧 Linux</summary> ```bash # Ubuntu/Debian sudo apt-get install tmux # Fedora sudo dnf install tmux # Arch sudo pacman -S tmux ``` </details> ### Setup for AI Assistants <details> <summary>🤖 Claude Desktop (via MCP)</summary> Add to your Claude Desktop configuration: ```json { "mcpServers": { "terminally-mcp": { "command": "node", "args": ["/path/to/terminally-mcp/build/index.js"] } } } ``` </details> <details> <summary>⚡ Cline/Other MCP Clients</summary> Add to your MCP client configuration: ```json { "terminally-mcp": { "command": "node", "args": ["/path/to/terminally-mcp/build/index.js"], "type": "stdio" } } ``` </details> ## 📖 API Reference ### 🔧 Available Tools #### `create_tab` Creates a new terminal session. ```typescript // Request { "name": "my-session" // Optional: custom name for the tab } // Response { "window_id": "@1" // Unique identifier for the created tab } ``` #### `execute_command` Run any shell command in a specific terminal tab. ```typescript // Request { "window_id": "@1", "command": "echo 'Hello, World!' && ls -la", "timeout": 5000 // Optional: timeout in ms (default: 10000) } // Response { "output": "Hello, World!\ntotal 64\ndrwxr-xr-x 10 user staff 320 Jan 15 10:00 ." } ``` #### `list_tabs` Get all active terminal sessions. ```typescript // Response { "tabs": [ { "window_id": "@0", "name": "default", "active": true }, { "window_id": "@1", "name": "my-session", "active": false } ] } ``` #### `read_output` Read the terminal buffer including history. ```typescript // Request { "window_id": "@1", "history_limit": 100 // Optional: number of history lines } // Response { "content": "$ echo 'Previous command'\nPrevious command\n$ ls\nfile1.txt file2.txt" } ``` #### `close_tab` Close a terminal session. ```typescript // Request { "window_id": "@1" } // Response { "success": true } ``` ## 💡 Examples ### Basic Command Execution ```javascript // Create a new terminal const tab = await mcp.call('create_tab', { name: 'dev-server' }); // Navigate and start a development server await mcp.call('execute_command', { window_id: tab.window_id, command: 'cd /my/project && npm run dev' }); // Check the output const output = await mcp.call('read_output', { window_id: tab.window_id }); ``` ### Multi-Tab Workflow ```javascript // Create tabs for different purposes const webTab = await mcp.call('create_tab', { name: 'web-server' }); const dbTab = await mcp.call('create_tab', { name: 'database' }); const testTab = await mcp.call('create_tab', { name: 'tests' }); // Start services in parallel await Promise.all([ mcp.call('execute_command', { window_id: webTab.window_id, command: 'npm run dev' }), mcp.call('execute_command', { window_id: dbTab.window_id, command: 'docker-compose up postgres' }) ]); // Run tests await mcp.call('execute_command', { window_id: testTab.window_id, command: 'npm test' }); ``` ### Complex Command Chains ```javascript // Execute multiple commands with proper escaping await mcp.call('execute_command', { window_id: '@1', command: ` echo "Setting up environment..." && export NODE_ENV=development && echo "Installing dependencies..." && npm install && echo "Running migrations..." && npm run migrate && echo "Starting application..." && npm start `.trim() }); ``` ## 🏗️ Architecture ``` terminally-mcp/ ├── src/ │ ├── index.ts # Entry point │ ├── server.ts # MCP server implementation │ ├── services/ │ │ └── tmuxManager.ts # tmux interaction layer │ └── tools/ │ ├── definitions.ts # Tool schemas │ └── handlers.ts # Tool implementations ├── test/ # Test suite ├── build/ # Compiled JavaScript └── package.json ``` ### Key Design Decisions - **🔐 Isolated tmux Server**: Each instance uses a unique socket path to prevent conflicts - **📍 Marker-Based Output Capture**: Reliable command output extraction using UUID markers - **⏱️ Timeout Protection**: Configurable timeouts prevent hanging on long-running commands - **🎯 Type Safety**: Full TypeScript implementation with strict typing ## 🧪 Development ```bash # Run in development mode (auto-rebuild) pnpm dev # Run tests pnpm test # Run tests with UI pnpm test:ui # Build for production pnpm build # Start production server pnpm start ``` ## 🤝 Contributing We love contributions! Whether it's: - 🐛 Bug reports - 💡 Feature requests - 📖 Documentation improvements - 🔧 Code contributions Please feel free to: 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to the branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request ## 📄 License This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details. ## 🙏 Acknowledgments - Built on the [Model Context Protocol](https://modelcontextprotocol.io) specification - Powered by [tmux](https://github.com/tmux/tmux) - the terminal multiplexer - Inspired by the need for better AI-terminal integration ## 🌟 Star History If you find this project useful, please consider giving it a ⭐ on GitHub! --- <div align="center"> **Built with ❤️ for the AI-assisted development community** [Report Bug](https://github.com/yourusername/terminally-mcp/issues) • [Request Feature](https://github.com/yourusername/terminally-mcp/issues) • [Join Discussion](https://github.com/yourusername/terminally-mcp/discussions) </div>