Skip to main content
Glama

Terminally MCP

by NightTrek

🖥️ Terminally MCP

Supercharge AI Assistants with Terminal Control Powers

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.

FeaturesQuick StartInstallationAPI ReferenceExamples


🎯 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

🎮 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

🔒 Safe & Isolated

  • Dedicated tmux server instance
  • No interference with user's tmux sessions
  • Timeout protection for long-running commands
  • Clean session management

🤖 AI-Optimized

  • MCP protocol compliance
  • Structured JSON responses
  • Error handling and recovery
  • Marker-based output capture

🛠️ Developer Friendly

  • TypeScript with full type safety
  • Comprehensive test suite
  • Clean, modular architecture
  • Easy to extend and customize

🚀 Quick Start

Get up and running in under 2 minutes!

# 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

brew install tmux
# Ubuntu/Debian sudo apt-get install tmux # Fedora sudo dnf install tmux # Arch sudo pacman -S tmux

Setup for AI Assistants

Add to your Claude Desktop configuration:

{ "mcpServers": { "terminally-mcp": { "command": "node", "args": ["/path/to/terminally-mcp/build/index.js"] } } }

Add to your MCP client configuration:

{ "terminally-mcp": { "command": "node", "args": ["/path/to/terminally-mcp/build/index.js"], "type": "stdio" } }

📖 API Reference

🔧 Available Tools

create_tab

Creates a new terminal session.

// 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.

// 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.

// 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.

// 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.

// Request { "window_id": "@1" } // Response { "success": true }

💡 Examples

Basic Command Execution

// 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

// 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

// 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

# 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 file for details.

🙏 Acknowledgments

  • Built on the Model Context Protocol specification
  • Powered by 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!


Built with ❤️ for the AI-assisted development community

Report BugRequest FeatureJoin Discussion

Related MCP Servers

  • -
    security
    F
    license
    -
    quality
    An MCP server that allows AI assistants like Claude to execute terminal commands on the user's computer and return the output, functioning like a terminal through AI.
    Last updated -
    47
    Python
    • Apple
  • A
    security
    A
    license
    A
    quality
    A server that enables AI assistants to execute terminal commands and retrieve outputs via the Model Context Protocol (MCP).
    Last updated -
    3
    16
    Python
    MIT License
    • Apple
    • Linux
  • -
    security
    A
    license
    -
    quality
    An enhanced MCP server that grants AI assistants the ability to execute terminal commands on a user's system with improved security controls, designed for use in controlled environments.
    Last updated -
    Python
    MIT License
    • Apple
  • A
    security
    F
    license
    A
    quality
    An MCP server that allows AI models to execute system commands on local machines or remote hosts via SSH, supporting persistent sessions and environment variables.
    Last updated -
    1
    673
    16
    TypeScript

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/NightTrek/Terminally-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server