🖥️ Shell MCP Server

🖥️ Shell MCP サーバー

🚀 Shell MCP サーバーを使って、AI アプリケーションに安全なシェルコマンド実行機能を追加しましょう！Model Context Protocol 向けに構築されています。

✨ 特長

• 🔒 安全な実行 - コマンドは指定されたディレクトリ内でのみ実行されます
• 🐚 複数のシェル - bash、sh、cmd、powershell に対応
• ⏱️ タイムアウト制御 - 長時間実行されるコマンドを自動的に終了します
• 🌍 クロスプラットフォーム - Unix と Windows の両システムで動作します
• 🛡️ デフォルトで安全 - ディレクトリとシェルの検証機能を内蔵しています

🚀 クイックスタート

インストール

# Using pip
pip install shell-mcp-server

# Using uv (recommended)
uv pip install shell-mcp-server

🔌 Claude Desktop との連携

シェルコマンドの実行を有効にするには、Claude Desktop の設定に以下を追加します。

{
    "mcpServers": {
        "shell-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/shell-mcp-server",
                "run",
                "shell-mcp-server",
                "/path/to/allowed/dir1",
                "/path/to/allowed/dir2",
                "--shell", "bash", "/bin/bash",
                "--shell", "zsh", "/bin/zsh"
            ]
        }
    }
}

🎮 使用例

基本的なファイル操作

# List directory contents
result = execute_command(
    command="ls -la",
    shell="bash",
    cwd="/path/to/project"
)

# Find files by pattern
result = execute_command(
    command="find . -name '*.py'",
    shell="bash",
    cwd="/path/to/project"
)

プロジェクト管理

# Git operations
result = execute_command(
    command="git status && git diff",
    shell="bash",
    cwd="/path/to/repo"
)

# Package management
result = execute_command(
    command="pip list --outdated",
    shell="bash",
    cwd="/path/to/python/project"
)

システム情報

# Resource usage
result = execute_command(
    command="df -h && free -h",
    shell="bash",
    cwd="/path/to/dir"
)

# Process monitoring
result = execute_command(
    command="ps aux | grep python",
    shell="bash",
    cwd="/path/to/dir"
)

ファイル処理

# Search file content
result = execute_command(
    command="grep -r 'TODO' .",
    shell="bash",
    cwd="/path/to/project"
)

# File manipulation
result = execute_command(
    command="awk '{print $1}' data.csv | sort | uniq -c",
    shell="bash",
    cwd="/path/to/data"
)

Windows 固有の例

# List processes
result = execute_command(
    command="Get-Process | Where-Object {$_.CPU -gt 10}",
    shell="powershell",
    cwd="C:\\path\\to\\dir"
)

# System information
result = execute_command(
    command="systeminfo | findstr /B /C:'OS'",
    shell="cmd",
    cwd="C:\\path\\to\\dir"
)

⚙️ 設定

コマンドライン引数で動作を設定します。

環境変数：

• COMMAND_TIMEOUT：⏱️ 最大実行時間（秒単位、デフォルト：30）

🛡️ セキュリティ機能

• 🔐 ディレクトリの分離：コマンドは指定されたディレクトリ内でのみ実行できます
• 🔒 シェルの制御：設定されたシェルのみ使用できます
• ⏰ タイムアウト保護：すべてのコマンドに設定可能なタイムアウトがあります
• 🛑 パスの検証：作業ディレクトリを検証し、パストラバーサル攻撃を防ぎます
• 👤 権限の分離：コマンドはサーバープロセスと同じ権限で実行されます

🛠️ 開発

開発環境をセットアップします。

# Create and activate virtual environment
uv venv
source .venv/bin/activate

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

# Run tests
python -m pytest

# Run tests with coverage
python -m pytest --cov=shell_mcp_server

🤝 コントリビューション

コントリビューションを歓迎します！お気軽に次のことを行ってください。

• 🐛 バグを報告する
• 💡 機能を提案する
• 🔧 プルリクエストを送る
• 📚 ドキュメントを改善する

📜 ライセンス

MIT ライセンスの詳細については、LICENSE を参照してください。