MCP Python Toolbox

MCP Python Toolbox

MCP クライアント（Claude Desktop など）に Python ワークスペース用ツールを提供する、ローカルの Model Context Protocol（stdio）サーバーです。ファイルの読み書き、Python の解析・フォーマット・リンティング、プロジェクトの .venv の管理、コードの実行ができます。

PyPI には公開されていません。実行環境はサンドボックス化されません。セキュリティを参照してください。

概要

ワークスペースディレクトリを指定してサーバーを起動します。接続した MCP クライアントは、次の操作ができます。

• ワークスペース内のファイルの読み取り、書き込み、削除、およびディレクトリの一覧表示
• Python コードの解析、フォーマット、リンティング
• 仮想環境の作成と依存関係のインストール
• ホスト上での Python スニペットの実行

機能

ファイル操作（FileOperations）

• ワークスペースディレクトリ内にスコープを限定したファイルツール
• パスを解決し、ワークスペースのルート外にある場合は拒否します
• 行を指定した操作でファイルを読み書きします（write_file は親ディレクトリを作成します）
• ファイルを削除します（delete_file はディレクトリを削除しません）
• メタデータ（サイズ、種類、更新日時）とともにディレクトリの内容を一覧表示します
• クラスには create_directory がありますが、MCP ツールとして登録されていません

コード解析（CodeAnalyzer）

• AST を使用して Python コードの構造を解析します
• 次の詳細情報を抽出します。
  • インポート文とそのエイリアス
  • 引数とデコレーターを含む関数定義
  • 基底クラスとメソッドを含むクラス定義
  • グローバル変数の代入
• 次の方法でコードをフォーマットします。
  • Black（デフォルト）
  • PEP8（autopep8 を使用）
• Pylint でリンティングします（JSON 出力、サブプロセスのタイムアウトは 30 秒）

プロジェクト管理（ProjectManager）

• ワークスペースに .venv を作成します（venv.create、pip を使用）
• pip を介して .venv に依存関係をインストールします。
  • requirements.txt から
  • pyproject.toml の [project.dependencies] から
• クラスの update_package／create_requirements_file は、.venv のインタープリターを使用します（pip install --upgrade／pip freeze）
• list_packages と check_conflicts は、ワークスペースの .venv ではなく、実行中のサーバーのインタープリターから参照できるパッケージを調べます（importlib.metadata）

コード実行（CodeExecutor）

• スニペットを一時ファイルに書き込み、subprocess で実行します
• .venv の Python インタープリターが存在する場合はそれを使用します
• stdout、stderr、終了コードを取得します
• オプションで作業ディレクトリを指定できます。FileOperations と同じ、パスを解決してワークスペース外なら拒否するチェックを行います（デフォルトはワークスペースのルート、シンボリックリンクによる範囲外へのアクセスも拒否します）
• タイムアウトを設定できます（デフォルトは 30 秒、最大 300 秒）。タイムアウトするとプロセスグループが強制終了され、部分的に出力された stdout／stderr が返されます
• 依然としてサンドボックス化されていません。同じユーザー権限で実行され、ファイルシステムとネットワークにアクセスできます。タイムアウト以外のリソース制限はありません

セキュリティ

サンドボックスはありません。サーバーとすべてのツールは、サーバーを起動したプロセスと同じ OS ユーザーおよび権限で実行されます。コンテナ、seccomp フィルター、インポート許可リスト、ネットワーク制限はありません。信頼できる MCP クライアントとワークスペースでのみ使用してください。

コードが実際に適用する制限は次のとおりです。

• read_file、write_file、delete_file、list_directory はパスを解決し、ワークスペースのルート外にあるパスを拒否します。Analyze、lint、format はこのチェックを使用しません。
• execute_python は引き続きサンドボックス化されていないホスト上での実行です。ワークスペースの .venv インタープリターを使って、一時的な .py ファイルを作成し、サブプロセスとして実行します。スニペットは、そのユーザーがアクセスできる場所であればどこでも読み書きでき、プロセスを起動し、ネットワークを使用できます。ガードは次の 2 つだけです。
  • タイムアウト（デフォルトは 30 秒。--execute-timeout、環境変数 MCP_PYTHON_EXECUTE_TIMEOUT、または呼び出しごとの timeout 引数で設定でき、上限は 300 秒）。時間切れになるとプロセスグループ全体が強制終了され、部分的な stdout/stderr は構造化エラーとして返されます。
  • working_dir は、FileOperations が使うものと同じワークスペースチェックで解決されます。シンボリックリンクによる脱出を含め、ワークスペース外に解決されるパスは拒否されます。デフォルトはワークスペースのルートです。
• その他のリソース制限（CPU、メモリ、オープンファイル、ネットワーク）はありません。
• create_venv と install_dependencies は .venv を作成し、pip でその環境にパッケージをインストールできます。

信頼できないクライアントにサーバーを公開しないでください。また、アシスタントによる変更や、そこからのコード実行を許容できないディレクトリツリーを --workspace に指定しないでください。

インストール

1. リポジトリをクローンします。

git clone https://github.com/gianlucamazza/mcp_python_toolbox.git
cd mcp_python_toolbox

2. 仮想環境を作成して有効化します。

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate  # Windows

3. 開発モードでパッケージをインストールします。

pip install -e ".[dev]"

使用方法

CLI ツールとして実行する

サーバーを起動する最も簡単な方法は、CLI を使用することです。

# Start with current directory as workspace
python -m mcp_python_toolbox

# Or specify a workspace directory
python -m mcp_python_toolbox --workspace /path/to/your/project

# Optional: default execute_python timeout in seconds (default 30, max 300)
python -m mcp_python_toolbox --execute-timeout 30
# or: export MCP_PYTHON_EXECUTE_TIMEOUT=30

Claude Desktop でのセットアップ

Claude Desktop は、MCP Python Toolbox サーバーを自動的に起動して管理できます。設定方法は次のとおりです。

1. 上記の説明に従って MCP Python Toolbox をインストールしてセットアップします
2. Claude Desktop の MCP ツール設定に Python Toolbox の設定項目を追加します。

"python-toolbox": {
  "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python",
  "args": [
    "-m",
    "mcp_python_toolbox",
    "--workspace",
    "/Users/username/path/to/workspace"
  ],
  "env": {
    "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src",
    "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
    "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv",
    "PYTHONHOME": ""
  }
}

3. パスをお使いの環境に合わせて変更します
4. 必要に応じて Claude Desktop が MCP サーバーを自動的に起動します
5. Claude は MCP インターフェースを通じて Python 開発ツールを利用できるようになります

プログラムからの使用

from mcp_python_toolbox import PythonToolboxServer

server = PythonToolboxServer(workspace_root="/path/to/your/project")
server.setup()
server.run()

コアモジュールの例

ファイル操作

from mcp_python_toolbox.core import FileOperations

file_ops = FileOperations(workspace_root="/path/to/project")

# Read file contents
content = file_ops.read_file("src/example.py")
# Read specific lines
lines = file_ops.read_file("src/example.py", start_line=10, end_line=20)

# Write to file
file_ops.write_file("output.txt", "Hello, World!")
# Append to file
file_ops.write_file("log.txt", "New entry\n", mode='a')

# List directory contents
contents = file_ops.list_directory("src")
for item in contents:
    print(f"{item['name']} - {item['type']} - {item['size']} bytes")

コード分析

from mcp_python_toolbox.core import CodeAnalyzer

analyzer = CodeAnalyzer(workspace_root="/path/to/project")

# Analyze Python file structure
analysis = analyzer.parse_python_file("src/example.py")
print(f"Found {len(analysis['functions'])} functions")
print(f"Found {len(analysis['classes'])} classes")

# Format code
formatted = analyzer.format_code(code, style='black')

# Lint code
issues = analyzer.lint_code("src/example.py")
for issue in issues:
    print(f"Line {issue['line']}: {issue['message']}")

プロジェクト管理

from mcp_python_toolbox.core import ProjectManager

pm = ProjectManager(workspace_root="/path/to/project")

# Create virtual environment
pm.create_virtual_environment()

# Install dependencies
pm.install_dependencies()  # from requirements.txt or pyproject.toml
pm.install_dependencies("requirements-dev.txt")  # from specific file

# Check for conflicts
conflicts = pm.check_dependency_conflicts()
if conflicts:
    print("Found dependency conflicts:")
    for conflict in conflicts:
        print(f"{conflict['package']} requires {conflict['requires']}")

# Update packages
pm.update_package("requests")  # to latest
pm.update_package("flask", version="2.0.0")  # to specific version

コード実行

from mcp_python_toolbox.core.code_executor import CodeExecutor

executor = CodeExecutor(workspace_root="/path/to/project")

code = '''
def greet(name):
    return f"Hello, {name}!"

print(greet("World"))
'''

result = executor.execute_code(code)
print(f"Output: {result['stdout']}")
print(f"Errors: {result['stderr']}")
print(f"Exit code: {result['exit_code']}")

開発

テスト

pytest

型チェック

mypy src/mcp_python_toolbox

Lint

pylint src/mcp_python_toolbox

フォーマット

black src/mcp_python_toolbox

コントリビューション

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

ライセンス

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

謝辞

• MCP サーバーは Python SDK（FastMCP）を使用して構築されています
• フォーマットには Black、Lint には Pylint を使用しています（サブプロセスで実行）