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

Tool	Description	Parameters
create_session	Create a new isolated tmux terminal session	session_id (optional string)
send_keys	Send a command to a specific tmux session	session_id (string), command (string)
get_screen	Return the current screen output of a tmux session	session_id (string)
interrupt	Send Ctrl+C to a running tmux session	session_id (string)
close_session	Kill a tmux terminal session	session_id (string)

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>