terminal-mcp

AI に本物のターミナルを。永続セッション。対話型プログラム。制限なし。

問題点

あらゆる AI コーディングツールが、同じ壁に突き当たります。本物のターミナルにアクセスできないのです。

Claude Code の Bash ツール、GitHub Copilot、Codex は、いずれもコマンドを独立したサブプロセスで実行します。コマンドごとに新しいプロセスが開始され、状態は引き継がれません。そのため、次のことができません。

• SSH セッション - リモートサーバーに接続し、複数のコマンドを実行できません
• REPL - Python、Node、Ruby のインタープリターを対話的に使えません
• データベース CLI - psql、mysql、redis-cli の接続を維持できません
• TUI アプリ - 矢印キーで htop、vim、fzf を操作できません
• 長時間実行プロセス - ビルドの監視、ログの確認、開発サーバーの実行ができません

解決策

terminal-mcp は AI エージェントに本物のターミナルを提供します。ツール呼び出しをまたいで維持される永続的な PTY セッションを利用できます。コマンドの送信、出力の読み取り、キー入力、TUI の操作を、人間がターミナルを使うのとまったく同じように行えます。

uvx terminal-mcp

コマンドは 1 つだけ。Claude Code、Claude Desktop、VS Code、Cursor、Windsurf で動作します。

クイックスタート

1. インストール（30 秒）

# No install needed - run directly
uvx terminal-mcp

# Or install globally
pip install terminal-mcp

2. AI クライアントに接続する

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

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

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

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

3. 動作を確認する

session_exec  exec="echo hello from terminal-mcp"

何ができますか？

リモートサーバーに SSH 接続する

session_create   command="ssh [email protected]"   label="prod"
session_interact session_id="a1b2c3d4"  input="df -h"  wait_for="\$"
session_interact session_id="a1b2c3d4"  input="docker ps"  wait_for="\$"
session_close    session_id="a1b2c3d4"

対話型 REPL を実行する

session_create   command="python3"  label="python"
session_interact session_id="e5f6g7h8"  input="import pandas as pd"  wait_for=">>>"
session_interact session_id="e5f6g7h8"  input="df = pd.read_csv('data.csv')"  wait_for=">>>"
session_interact session_id="e5f6g7h8"  input="df.describe()"  wait_for=">>>"
session_close    session_id="e5f6g7h8"

データベースにクエリを実行する

session_create   command="psql -U admin mydb"  label="db"
session_interact session_id="x1y2z3w4"  input="SELECT count(*) FROM users;"  wait_for="row"
session_interact session_id="x1y2z3w4"  input="\dt"  wait_for="#"
session_close    session_id="x1y2z3w4"

TUI アプリを操作する

session_create   command="htop"  label="monitor"
session_read     session_id="a1b2c3d4"
# Auto-detects TUI, returns screen snapshot

session_send     session_id="a1b2c3d4"  key="F6"
session_read     session_id="a1b2c3d4"  mode="diff"
# Returns only changed lines - saves tokens

session_send     session_id="a1b2c3d4"  key="F10"
session_close    session_id="a1b2c3d4"

長時間実行されるビルドを監視する

session_create   command="bash"  label="build"
session_send     session_id="a1b2c3d4"  input="npm run build"
session_wait_for session_id="a1b2c3d4"  pattern="Build complete|ERROR"  timeout=120

単発コマンドを実行する

session_exec  exec="git log --oneline -10"
session_exec  exec="docker compose ps"  timeout=10

主な機能

ツールリファレンス

terminal-mcp は 9 個の MCP ツールを公開します。詳しくはdocs/tools.mdをご覧ください。

アーキテクチャ

flowchart LR
    Client[AI Client] -->|MCP JSON-RPC| Server[terminal-mcp]
    Server --> SM[Session Manager]
    SM --> S1[PTY 1: bash]
    SM --> S2[PTY 2: python3]
    SM --> S3[PTY 3: ssh user@host]
    S1 & S2 & S3 -.->|PTY output| Reader[Reader Thread]
    Reader -.->|buffer| Server

各セッションは、pexpect.spawn（Windows では PopenSpawn）を介して実際の PTY を使用します。アーキテクチャの詳細は、docs/architecture.mdをご覧ください。

設定

すべての設定は TERMINAL_MCP_* 環境変数で指定できます。設定の詳細はdocs/configuration.mdをご覧ください。

カスタム設定の例：

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"],
      "env": {
        "TERMINAL_MCP_MAX_SESSIONS": "20",
        "TERMINAL_MCP_IDLE_TIMEOUT": "3600",
        "TERMINAL_MCP_TRUNCATION_MODE": "head_tail"
      }
    }
  }
}

ドキュメント

Supported Clients

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

Contributing

Contributions welcome! See docs/contributing.md for guidelines.

License

MIT