MCP Terminal Server

MCP ターミナルサーバー

Model Context Protocol（MCP）を実装した、安全なターミナル実行サーバーです。このサーバーは、セキュリティ機能とリソース制限を備えた、制御可能なコマンド実行機能を提供します。

機能

• コマンド実行：出力の取得とエラー処理を行いながら、シェルコマンドを実行します
• セキュリティ制御：実行可能なコマンドを制限し、コマンドインジェクションを防止します
• リソース制御：
  • コマンドのタイムアウト
  • 出力サイズの上限
• MCP プロトコルのサポート：
  • 標準の MCP メッセージ形式
  • 機能の通知
  • 出力のストリーミングをサポート

開発

ローカル環境のセットアップ

# Clone the repository
git clone https://github.com/RinardNick/mcp-terminal.git
cd mcp-terminal

# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install development dependencies
uv pip install -e ".[dev]"

PyPI への公開

# Build the package
uv pip install build
python -m build

# Upload to PyPI
uv pip install twine
python -m twine upload dist/*

MCP Inspector でのテスト

MCP Inspector ツールを使用して、サーバーの実装をテストできます。

# Install inspector
npm install -g @modelcontextprotocol/inspector

# Test server
npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd"

テストの実行

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_terminal.py

# Run with coverage
pytest --cov=mcp_terminal tests/

Claude Desktop での使用

パッケージを PyPI に公開した後、次の手順を実行します。

1. UV をインストールする（まだインストールされていない場合）：

   pip install uv
   

2. UV を使用してパッケージをインストールする：

   uv pip install mcp-terminal
   

3. Claude Desktop を設定する： Claude Desktop の設定ファイルを編集します（通常、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json にあります）。

   {
     "mcpServers": {
       "terminal": {
         "command": "uv",
         "args": [
           "pip",
           "run",
           "mcp-terminal",
           "--allowed-commands",
           "python,pip,git,ls,cd",
           "--timeout-ms",
           "30000",
           "--max-output-size",
           "1048576"
         ]
       }
     }
   }
   

プロトコルの実装

このサーバーは Model Context Protocol（MCP）を実装しており、次の機能を備えています。

機能の通知

{
  "protocol": "1.0.0",
  "name": "terminal",
  "version": "1.1.0",
  "capabilities": {
    "execute": {
      "description": "Execute a terminal command",
      "parameters": {
        "command": {
          "type": "string",
          "description": "The command to execute"
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "exitCode": { "type": "number" },
          "stdout": { "type": "string" },
          "stderr": { "type": "string" },
          "startTime": { "type": "string" },
          "endTime": { "type": "string" }
        }
      }
    }
  }
}

メッセージ形式

リクエスト：

{
  "type": "execute",
  "data": {
    "command": "echo 'hello world'"
  }
}

レスポンス：

{
  "type": "result",
  "data": {
    "command": "echo 'hello world'",
    "exitCode": 0,
    "stdout": "hello world\n",
    "stderr": "",
    "startTime": "2024-01-20T12:34:56.789Z",
    "endTime": "2024-01-20T12:34:56.790Z"
  }
}

エラー：

{
  "type": "error",
  "data": {
    "message": "command not allowed"
  }
}

セキュリティに関する考慮事項

1. コマンドの検証：

   • 許可されたコマンドのみ実行できます
   • シェル演算子はブロックされます
   • コマンドインジェクションの試みを防止します

2. リソースの保護：

   • コマンドのタイムアウトにより、処理の停止を防ぎます
   • 出力サイズの上限により、メモリの枯渇を防ぎます
   • あらゆる失敗ケースに対応するエラー処理

3. ベストプラクティス：

   • 本番環境では必ず allowed-commands を設定してください
   • タイムアウトとサイズの上限は、余裕を持った値に設定してください
   • コマンド実行ログを監視してください

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. Pull Request を作成します

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。