Which integrations are available for this server?

Used as the runtime environment for the MCP server with specific version requirements (v16+). Allows execution of shell commands with full output capture, proper quote/escape handling, and timeout protection. Provides tools for creating and managing terminal sessions, executing shell commands, reading terminal history, and controlling multiple terminal tabs in an isolated tmux environment.

How do I use Terminally MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Terminally MCP create a new terminal tab and run 'npm install' in it" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

🖥️ Terminally MCP

Supercharge AI Assistants with Terminal Control Powers ⚡

MCP Protocol Node.js TypeScript License: 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 • Quick Start • Installation • API Reference • Examples

🎯 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!

Related MCP server: MCP Terminal

✨ 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:

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
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 Bug • Request Feature • Join Discussion

Terminally MCP