Terminally MCP

🖥️ 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.

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!

✨ 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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

An MCP server that gives AI assistants the ability to create, manage, and control terminal sessions through a safe, isolated tmux environment.

Related MCP Servers

Terminal MCP Server
theailanguage
-
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
MCP Terminal
sichang824
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
Lilith Shell
charles-adedotun
-
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
Terminal MCP Server
weidwonder
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