NightTrek/Terminally-mcp

🎯 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

🚀 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

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

{
  "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 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!