Terminal MCP Server

Smart terminal session management for AI assistants. Solve terminal blocking issues with async execution, auto cleanup, and real-time web monitoring.

Support up to 64 concurrent terminals with intelligent idle detection, system monitoring, and auto browser opening.

---

✨ Key Features

• 🚀 Async Execution - Commands never block AI operations
• 🔢 Multi-Terminal - Up to 64 concurrent sessions
• 🧹 Auto Cleanup - Intelligent idle session detection
• ⚡ Broadcast - Execute commands across multiple terminals
• 📊 System Monitor - Real-time CPU/Memory/GPU tracking
• 🌐 Web Interface - Auto-open browser with full terminal view
• 🖥️ Smart Shell - Auto-detect best shell (Git Bash > PowerShell > cmd)
• 🛑 Resource Control - One-click shutdown button

---

🚀 Quick Start

Step 1: Add MCP Configuration

Add to your Cursor MCP config:

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp-server"]
    }
  }
}

Or for Node.js:

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "@kanniganfan/terminal-mcp"]
    }
  }
}

Step 2: ⚠️ IMPORTANT - Add IDE Rule

To make AI always use this MCP for terminal operations, add this rule to your IDE's Project Rules or User Rules:

All terminal operations (read/write) must be proxied through the Terminal MCP.
Use MCP tools for all terminal commands instead of direct terminal access.

In Cursor:

• Settings → Rules → Add this rule
• Or in .cursorrules file in your project root

Why this is important:

• ✅ Prevents AI from getting stuck in terminal
• ✅ All commands run asynchronously
• ✅ Can monitor all terminals in web interface
• ✅ Better resource management

Step 3: Restart Cursor

Step 4: Start Using

In Cursor:

Create a terminal session named "dev"
Execute "npm run dev" in dev session

Browser auto-opens → View real-time output → Monitor system resources!

---

📊 Web Interface

Auto-opens at http://localhost:18888

Dashboard Features

Top Panel:

• 📊 CPU Usage (real-time)
• 💾 Memory Usage (% + GB)
• 🖥️ GPU Info (Windows)
• 📈 Session Stats
• 🛑 Shutdown Server Button

Layout:

• Left: Terminal session list
• Right: Full-screen xterm.js terminal (click to expand)
• Bottom: Command input

Actions

• Click session → Full terminal expands
• Type commands → Real-time execution
• Click 🛑 → Shutdown all sessions + release port

---

🛠️ Available MCP Tools

Tool	Description
create_session	Create new terminal session
execute_command	Execute command (async, non-blocking)
broadcast_command	Execute across multiple terminals
get_all_sessions	List all sessions
get_session_status	Get session status
get_output	Get terminal output
kill_session	Terminate session
cleanup_idle_sessions	Clean idle sessions
get_stats	Get statistics

---

⚙️ Configuration

Edit config.json:

{
  "max_sessions": 64,
  "idle_timeout": 300,
  "auto_cleanup_interval": 60,
  "max_output_lines": 10000,
  "web_port": 18888,
  "auto_open_browser": true
}

---

🖥️ Smart Shell Detection

Windows Priority:

1. Git Bash (C:\Program Files\Git\bin\bash.exe)
2. PowerShell 7 / Windows PowerShell
3. cmd.exe (fallback)

Linux/Mac: Uses $SHELL environment variable

---

📁 Project Structure

terminal-mcp/
├── src/terminal_mcp_server/
│   ├── server.py          # Core MCP server (all-in-one)
│   └── config.json        # Default configuration
├── config.json            # User configuration
├── mcp_config_example.json # Cursor config template
├── requirements.txt       # Dependencies
└── README.md             # This file

---

🎯 Use Cases

Development Workflow

1. Create "frontend" → npm run dev
2. Create "backend" → python manage.py runserver
3. Create "database" → docker-compose up
4. Monitor all in web interface
5. Click any terminal to view full output

Batch Operations

1. Create 5 sessions
2. Broadcast "git status" to all
3. View results in web interface

Long-running Tasks

1. Create session
2. Execute "npm run build"
3. AI continues other work
4. Check output anytime in browser

---

🛑 Resource Management

When switching IDEs or done working:

1. Open web interface
2. Click 🛑 Shutdown Server button
3. All sessions terminated
4. Port 18888 released
5. Process fully exits

No more port conflicts or resource leaks!

---

📦 Installation

Python Users (PyPI)

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp-server"]
    }
  }
}

Node.js Users (npm)

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["-y", "@kanniganfan/terminal-mcp"]
    }
  }
}

Or install globally first:

npm install -g @kanniganfan/terminal-mcp

Then use:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp"
    }
  }
}

No download, no install, just works!

---

🔧 Troubleshooting

Web Interface Not Opening

Solution: Manually visit http://localhost:18888

Port Already in Use

Solution:

1. Change web_port in config.json
2. Or click shutdown button in existing web interface

Shell Not Detected

Solution: Check that Git Bash/PowerShell is installed

---

📄 License

MIT License - see LICENSE file

---

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md

---

🌟 Star History

If this helps you, please give it a star! ⭐

---

Made with ❤️ for AI Assistants | Report Issues