Terminal MCP Server

An MCP (Model Context Protocol) server that allows AI agents to create and interact with isolated tmux terminal sessions in real time.

Features

• Create sessions — spin up isolated tmux terminals on demand

• Send commands — execute shell commands in any session

• Read output — capture live terminal screen content

• Interrupt — send Ctrl+C to running processes

• Close sessions — clean up when done

Tools

Requirements

• Python 3.10+

• tmux

• mcp package (mcp>=1.28.0)

Installation

pip install -r requirements.txt

Usage

Run the server

python Server.py

Configure in opencode

Add to your opencode.json:

{
  "mcp": {
    "terminal": {
      "type": "local",
      "command": ["python", "/path/to/Server.py"],
      "enabled": true
    }
  }
}

Test manually

from mcp import StdioClient
import asyncio

async def test():
    async with StdioClient("python Server.py") as client:
        result = await client.call_tool("create_session", {"session_id": "test-1"})
        print(result)
        result = await client.call_tool("send_keys", {"session_id": "test-1", "command": "echo hello"})
        screen = await client.call_tool("get_screen", {"session_id": "test-1"})
        print(screen)

asyncio.run(test())

How it works

Each session is backed by a tmux window. Commands are sent via tmux send-keys, output is captured via tmux capture-pane. Sessions persist until explicitly closed.

You can attach to any running session to watch the AI interact in real time:

tmux attach -t <session_id>