pip不要！uvでMCPサーバーをスマートに実行する手順まとめ


Pythonのツールをインストールする際、従来は`pip install`を使ってグローバルに導入する方法が一般的でした。しかし、この方法では環境が汚染されたり、パッケージのバージョン競合が発生したりする問題があります。

最近、AI関連ツールのMCPサーバーでも、`uv`での実行が推奨されるケースが増えています。この記事では、`pip install`での手順が示されている[Weather MCP Server](https://github.com/isdaniel/mcp_weather_server)を例に、`uv tool`を使ってシステムを汚さずにインストール・実行する方法を解説します。

## 従来のインストール方法

Weather MCP Serverの公式手順では、以下のようにインストールし、実行する方法が紹介されています。

```bash
pip install mcp_weather_server
# インストール後の実行
python -m mcp_weather_server
```

この手順だと、Pythonのシステム環境にパッケージが直接インストールされるため、後々のバージョン管理や依存関係の整理が難しくなります。

## uv toolとは

[uv](https://github.com/astral-sh/uv)は、高速なPythonパッケージインストーラーであり、仮想環境の管理やモジュールの実行機能も備えたツールです。

※uvのインストール方法については、[公式ドキュメント](https://github.com/astral-sh/uv#installation)を参照してください。

### 基本的な使い方

```bash
uv tool run <module_name>
```

### uvの主なメリット

1. **高速起動**: uvは起動が速く、モジュール実行もスムーズ
2. **依存関係の自動解決**: `pyproject.toml`や`requirements.txt`を参照して必要なパッケージを自動でインストール
3. **仮想環境の自動管理**: 必要に応じて一時的な仮想環境を生成し、実行環境を隔離（`tool install`によってキャッシュされ、再利用も可能）

## Weather MCP Serverをuvで導入する

1. **パッケージのインストール**

   ```bash
   uv tool install mcp_weather_server
   ```
2. **実行**

   ```bash
   uv tool run mcp_weather_server
   ```

しかし、このまま実行すると以下のようなエラーが発生します。

```bash
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.
```

このエラーは、パッケージ名と実行可能モジュール名が異なることが原因です（パッケージ名はハイフン区切り、実行ファイルはアンダースコア区切りなど）。

エラーメッセージの指示に従い、以下のコマンドで実行してみましょう。

```bash
uv tool run --from mcp-weather-server mcp_weather_server
```

すると、今度は依存パッケージが見つからないというエラーが表示されます。

```bash
ModuleNotFoundError: No module named 'dateutil'
```

この場合、`--with`オプションで不足しているパッケージを追加します。

```bash
uv tool install --with python-dateutil mcp_weather_server
```

`--with`オプションは、`pyproject.toml`や`requirements.txt`が存在しないパッケージでも、手動で依存関係を追加できる機能です。これにより：

* システム環境や既存の仮想環境を汚染せずに依存関係が解決
* 次回以降の`tool run`実行時も同一環境が自動的に再現される

以上で、以下のコマンドがエラーなく動作するはずです。

```bash
uv tool run --from mcp-weather-server mcp_weather_server
```

> ※`uv tool run`は実行ごとに一時的な仮想環境を生成するため、都度パッケージのインストールが発生することがあります。頻繁に利用する場合は`tool install`での事前準備が推奨されます。

### MCPサーバー用設定例

MCPクライアントの設定ファイル（`servers.json`など）に追加する例を示します。

```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "mcp-weather-server",
        "mcp_weather_server"
      ]
    }
  }
}
```


### Neovimでの動作確認

neovim + avante.nvim + mcphub.nvimの構成で、上記の設定を使ってWeather MCP Serverを呼び出します。

![Screenshot from 2025-05-18 19-37-23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2591762/a8fa2c71-e360-4498-a00a-cdd2e4f2d898.png)

MCPクライアントからの質問と、それに対するWeather MCP Serverの回答が正しく表示され、意図通り動作していることが確認できました。

## 注意点

* uvは比較的新しいツールのため、環境によっては動作が安定しない場合があります。
* 一部のパッケージはuvと完全互換でない可能性があります。
* 特殊な環境変数や設定を必要とするスクリプトは、追加のオプション設定が必要になる場合があります。

## まとめ

`uv tool`を使ったモジュールのインストール・実行は、従来の`python -m`方式と比べて以下の利点があります。

* 依存関係の自動管理
* コマンドがシンプル
* 実行環境の分離と再現性の確保

MCPサーバーを扱う場面では、`uv tool`を活用することで、よりクリーンかつ効率的にツールを実行できるようになります。ぜひ試してみてください。