Pythonのツールをインストールする際、従来はpip installを使ってグローバルに導入する方法が一般的でした。しかし、この方法では環境が汚染されたり、パッケージのバージョン競合が発生したりする問題があります。
最近、AI関連ツールのMCPサーバーでも、uvでの実行が推奨されるケースが増えています。この記事では、pip installでの手順が示されているWeather MCP Serverを例に、uv toolを使ってシステムを汚さずにインストール・実行する方法を解説します。
従来のインストール方法
Weather MCP Serverの公式手順では、以下のようにインストールし、実行する方法が紹介されています。
pip install mcp_weather_server
# インストール後の実行
python -m mcp_weather_server
この手順だと、Pythonのシステム環境にパッケージが直接インストールされるため、後々のバージョン管理や依存関係の整理が難しくなります。
uv toolとは
uvは、高速なPythonパッケージインストーラーであり、仮想環境の管理やモジュールの実行機能も備えたツールです。
※uvのインストール方法については、公式ドキュメントを参照してください。
基本的な使い方
uv tool run <module_name>
uvの主なメリット
- 高速起動: uvは起動が速く、モジュール実行もスムーズ
-
依存関係の自動解決:
pyproject.tomlやrequirements.txtを参照して必要なパッケージを自動でインストール -
仮想環境の自動管理: 必要に応じて一時的な仮想環境を生成し、実行環境を隔離（
tool installによってキャッシュされ、再利用も可能）
Weather MCP Serverをuvで導入する
-
パッケージのインストール
uv tool install mcp_weather_server -
実行
uv tool run mcp_weather_server
しかし、このまま実行すると以下のようなエラーが発生します。
The executable `mcp-weather-server` was not found.
warning: An executable named `mcp-weather-server` is not provided by package `mcp-weather-server`.
The following executables are provided by `mcp-weather-server`:
- mcp_weather_server
Consider using `uv tool run --from mcp-weather-server <EXECUTABLE_NAME>` instead.
このエラーは、パッケージ名と実行可能モジュール名が異なることが原因です（パッケージ名はハイフン区切り、実行ファイルはアンダースコア区切りなど）。
エラーメッセージの指示に従い、以下のコマンドで実行してみましょう。
uv tool run --from mcp-weather-server mcp_weather_server
すると、今度は依存パッケージが見つからないというエラーが表示されます。
ModuleNotFoundError: No module named 'dateutil'
この場合、--withオプションで不足しているパッケージを追加します。
uv tool install --with python-dateutil mcp_weather_server
--withオプションは、pyproject.tomlやrequirements.txtが存在しないパッケージでも、手動で依存関係を追加できる機能です。これにより：
- システム環境や既存の仮想環境を汚染せずに依存関係が解決
- 次回以降の
tool run実行時も同一環境が自動的に再現される
以上で、以下のコマンドがエラーなく動作するはずです。
uv tool run --from mcp-weather-server mcp_weather_server
※
uv tool runは実行ごとに一時的な仮想環境を生成するため、都度パッケージのインストールが発生することがあります。頻繁に利用する場合はtool installでの事前準備が推奨されます。
MCPサーバー用設定例
MCPクライアントの設定ファイル（servers.jsonなど）に追加する例を示します。
{
"mcpServers": {
"weather": {
"command": "uv",
"args": [
"tool",
"run",
"--from",
"mcp-weather-server",
"mcp_weather_server"
]
}
}
}
Neovimでの動作確認
neovim + avante.nvim + mcphub.nvimの構成で、上記の設定を使ってWeather MCP Serverを呼び出します。
MCPクライアントからの質問と、それに対するWeather MCP Serverの回答が正しく表示され、意図通り動作していることが確認できました。
注意点
- uvは比較的新しいツールのため、環境によっては動作が安定しない場合があります。
- 一部のパッケージはuvと完全互換でない可能性があります。
- 特殊な環境変数や設定を必要とするスクリプトは、追加のオプション設定が必要になる場合があります。
まとめ
uv toolを使ったモジュールのインストール・実行は、従来のpython -m方式と比べて以下の利点があります。
- 依存関係の自動管理
- コマンドがシンプル
- 実行環境の分離と再現性の確保
MCPサーバーを扱う場面では、uv toolを活用することで、よりクリーンかつ効率的にツールを実行できるようになります。ぜひ試してみてください。