Claude Codeを利用してReact/VueのフロントエンドからPythonバックエンドのAPIクライアントを自動生成しようとしたところ、MCPツールの実行でハマったので備忘録として残します。
目次
この記事でわかること
- Claude CodeのMCP経由でPythonを実行する際の環境変数の挙動
- KeyErrorが発生する根本的な理由と隔離環境の仕様
- MCP設定ファイルへの環境変数定義方法
- python-dotenvを利用した確実なロード手順
[現象] MCP経由のPython実行でKeyErrorが発生
Claude Codeから自作のMCPツール（execute_pythonなど）を呼び出し、DB連携を含むスクリプトを実行しようとすると、以下のエラーが発生して停止します。
Error: MCP tool 'execute_python' failed:
KeyError: 'DB_CONNECTION_STRING' (Subprocess exited with non-zero code 1)[環境]
- Tool: Claude Code
- Protocol: Model Context Protocol (MCP)
- Backend: Python 3.x
- Task: APIクライアントの自動生成およびDBメタデータの取得
[原因] 環境変数の継承ブロック
原因は、Claude CodeのMCPサーバーが子プロセスを実行する際、OS側のシェル環境変数を自動的に継承しないことにあります。
通常、ターミナルで export VAR=value と設定すれば実行中のプログラムから参照できますが、MCP経由ではセキュリティとポータビリティの観点から実行環境が隔離されています。公式ドキュメントではツールの登録方法は詳しく記載されていますが、この「環境変数の注入」については見落としやすいポイントです。
[解決策] 環境変数を明示的に渡す2つの方法
方法1：MCP設定ファイルに定義する（推奨）
anthropic-mcp-config.json の env オブジェクトに必要な変数を記述します。これが最もクリーンな解決策です。
{
"mcpServers": {
"my-python-tool": {
"command": "python",
"args": ["path/to/script.py"],
"env": {
"DB_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/db"
}
}
}
}方法2：Pythonスクリプト内で明示的にロードする
設定ファイルに秘匿情報を書きたくない場合や、既存の .env ファイルを流用したい場合は、python-dotenv を使用します。ただし、カレントディレクトリを明示的に指定する必要があります。
# 修正後のコード
import os
from dotenv import load_dotenv
# カレントディレクトリから.envを確実に読み込む
load_dotenv(os.path.join(os.getcwd(), '.env'))
connection_string = os.environ["DB_CONNECTION_STRING"]設定方法の比較
| 手法 | メリット | デメリット |
|---|---|---|
| config.json (env) | 管理が容易、Claude Codeに直結 | 設定ファイルに機密情報が残る |
| python-dotenv | 既存の.envを流用可能 | コード側にロード処理の記述が必要 |
[まとめ]
Claude Codeで「環境変数が見つからない」というエラーが出た際は、MCPの実行環境がホストシェルから隔離されていることを疑いましょう。anthropic-mcp-config.json に env を追加することで、ほとんどのKeyErrorは解消可能です。フルスタック開発の自動化を止めることなく、快適なコーディング環境を整えていきましょう！
