👨‍💻

MCPサーバをPythonで開発するなら uv/uvx 一択！完全ガイド

shinya.hara

2025/10/26に公開

Model Context Protocol

uvx

tech

最近、カスタムMCP開発の勉強をしているのですが、その際にuv/uvxについて疑問に思ったことなどいろいろ調べた情報を生成AIに依頼して記事化しましたので、参考になれば幸いです。

はじめに

MCP (Model Context Protocol) サーバを Python で開発したいけど、環境構築が面倒...

そんなあなたに朗報です。uv/uvx を使えば、Python未インストールのPCでも即座に動作します。

この記事では、MCPサーバ開発における uv/uvx の圧倒的なメリットと、その仕組みを徹底解説します。

TL;DR（結論）

✅ Python不要: ユーザーのPCにPythonがなくても動く
✅ 1コマンドで完結: claude mcp add だけで全自動セットアップ
✅ 超高速: Rust製で pip の 10～100倍速い
✅ バージョン管理: プロジェクトごとに適切なPythonバージョンを自動管理
✅ クリーン: システム環境を一切汚さない

従来の方法 vs uv/uvx

従来の方法（pip/venv）の課題

# ユーザーがやる必要があること

# 1. Pythonのインストール (公式サイトからダウンロード)
# 2. 環境変数PATHの設定
# 3. 仮想環境の作成
python -m venv .venv

# 4. 仮想環境の有効化 (OS依存)
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# 5. 依存パッケージのインストール
pip install -r requirements.txt

# 6. MCPサーバの起動設定（手動でJSONファイル編集）
# Windows: %USERPROFILE%\.claude.json
# macOS/Linux: ~/.claude.json

問題点:

😫 手順が多すぎる（7～8ステップ）
😫 OS依存の違いでトラブル頻発
😫 Pythonバージョン不一致でエラー
😫 システム環境が汚れる
😫 JSONの手動編集でミスが起きやすい

uv/uvx を使う方法

パターン1: コマンド一発（Claude Code推奨）

# たったこれだけ！
claude mcp add --transport stdio my-mcp-server --scope user -- \
  uvx --from git+https://github.com/user/repo.git my-mcp-server

パターン2: 設定ファイル（Claude Code / Gemini CLI / Cline 対応）

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/user/repo.git",
        "my-mcp-server"
      ]
    }
  }
}

設定ファイルの場所:

Claude Code: %USERPROFILE%\.claude.json (Windows) / ~/.claude.json (macOS/Linux)
Gemini CLI: %USERPROFILE%\.gemini\settings.json (Windows) / ~/.gemini/settings.json (macOS/Linux)
Cline (VS Code): VS Code設定 cline.mcpServers

メリット:

✅ 1コマンドで完結（コマンドパターン）
✅ JSONコピペで完結（設定ファイルパターン）
✅ Python未インストールでもOK
✅ OS依存の問題ゼロ
✅ 自動バージョン管理

uv/uvx とは？

uv

Rust製の超高速Pythonパッケージマネージャー

従来の pip + venv の代替
10～100倍高速
依存関係の解決が賢い
プロジェクト単位の環境管理

uvx

uv の一時実行コマンド（pipx の代替）

グローバルインストール不要
一時的な仮想環境を自動作成
Pythonインタプリタも自動ダウンロード

MCPサーバ配布の仕組み（完全図解）

全体アーキテクチャ

┌───────────────────────────────────────────────────────────────────┐
│ ユーザーのPC (Python未インストールでもOK!)                          │
├───────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────────────────────────────────────────────┐            │
│  │ MCPホスト (Claude Code / Gemini CLI / Cline)     │            │
│  ├──────────────────────────────────────────────────┤            │
│  │ 設定ファイル:                                     │            │
│  │ - .claude.json (Claude Code)                    │            │
│  │ - .gemini/settings.json (Gemini CLI)            │            │
│  │ - VS Code設定 (Cline)                            │            │
│  │                                                  │            │
│  │ {                                                │            │
│  │   "mcpServers": {                                │            │
│  │     "my-server": {                               │            │
│  │       "command": "uvx",                          │            │
│  │       "args": ["--from", "git+...", "server"]    │            │
│  │     }                                            │            │
│  │   }                                              │            │
│  │ }                                                │            │
│  └──────────────────┬───────────────────────────────┘            │
│                     │                                             │
│                     │ MCP Protocol (stdio)                        │
│                     ↓                                             │
│  ┌──────────────────────────────────────────────────┐            │
│  │ uvx (Rust製ランタイム)                            │            │
│  ├──────────────────────────────────────────────────┤            │
│  │ 1. pyproject.toml を読み込み                      │            │
│  │ 2. 必要なPythonバージョンを判定 (例: >=3.10)       │            │
│  │ 3. Pythonインタプリタを自動ダウンロード            │            │
│  │    → C:\Users\xxx\AppData\Roaming\uv\python\    │            │
│  │ 4. 依存パッケージを自動インストール                │            │
│  │    → C:\Users\xxx\AppData\Local\uv\cache\       │            │
│  │ 5. 一時的な仮想環境で実行                          │            │
│  └──────────────────┬───────────────────────────────┘            │
│                     ↓                                             │
│  ┌──────────────────────────────────────────────────┐            │
│  │ あなたのMCPサーバ (Python)                         │            │
│  ├──────────────────────────────────────────────────┤            │
│  │ - mcp_server.py                                  │            │
│  │ - その他モジュール                                  │            │
│  │ - 依存パッケージ (pandas, numpy, etc.)             │            │
│  └──────────────────────────────────────────────────┘            │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

処理フロー（時系列）

ファイルシステム構造

uvx が管理するディレクトリ

C:\Users\{username}\AppData\
├── Roaming\uv\
│   └── python\                    ← Pythonインタプリタ
│       ├── cpython-3.10.18-windows-x86_64-none\
│       ├── cpython-3.12.12-windows-x86_64-none\  ← uv が自動DL
│       │   ├── python.exe
│       │   ├── Lib\
│       │   └── Scripts\
│       └── cpython-3.9.22-windows-x86_64-none\
│
└── Local\uv\cache\               ← パッケージキャッシュ
    ├── git-v0\                   ← GitHubからのコード
    │   └── checkouts\
    │       └── {repo-hash}\
    │           └── {commit-hash}\  ← コミット別に保存
    │               ├── src\
    │               │   └── your_package\
    │               │       ├── mcp_server.py
    │               │       └── ...
    │               ├── pyproject.toml
    │               └── README.md
    │
    ├── wheels-v5\                ← pipパッケージ (wheel形式)
    │   ├── pandas-2.1.0-...whl
    │   ├── numpy-1.24.0-...whl
    │   └── ...
    │
    ├── environments-v2\          ← 仮想環境（一時的）
    │
    └── simple-v18\               ← PyPIインデックス

キャッシュの再利用

# 初回実行
$ uvx --from git+https://github.com/user/repo.git my-server
# → 5～10秒（ダウンロード + セットアップ）

# 2回目以降
$ uvx --from git+https://github.com/user/repo.git my-server
# → 0.5秒（キャッシュから起動）⚡

# コードが更新されたら
$ uvx --from git+https://github.com/user/repo.git my-server
# → uvが自動検出して最新版をダウンロード
# → 新しいコミットハッシュのディレクトリに保存

pyproject.toml の重要性

uvx は pyproject.toml を読んで全自動セットアップします。

最小構成

[project]
name = "my-mcp-server"
version = "0.1.0"
requires-python = ">=3.10"  # ← uvがこれを見てPython自動DL

dependencies = [
    "mcp>=0.9.0",
    "pandas>=2.0.0",
]

[project.scripts]
my-mcp-server = "my_package.server:main"  # ← エントリーポイント

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

uvx の挙動

# uvx が pyproject.toml を見て自動実行すること：

1. requires-python = ">=3.10" を確認
   → Python 3.12.12 を自動ダウンロード（なければ）

2. dependencies をインストール
   → mcp, pandas を wheels-v5/ にキャッシュ

3. project.scripts を確認
   → my_package.server:main を実行可能コマンドとして登録

4. 一時環境で起動
   → sys.path に適切なパスを設定

実例：Survey Insight MCP Server

配布方法

GitHub + uvx の組み合わせ

方法1: コマンドラインでインストール（Claude Code）

# Claude Code の場合
claude mcp add --transport stdio survey-insight --scope user -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git \
  survey-insight-mcp

方法2: 設定ファイルで登録（全MCPホスト対応）

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ]
    }
  }
}

Gemini CLI (~/.gemini/settings.json):

{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ]
    }
  }
}

Cline (VS Code設定):

{
  "cline.mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ]
    }
  }
}

pyproject.toml（抜粋）

[project]
name = "survey-insight"
version = "0.3.1"
requires-python = ">=3.10"

dependencies = [
    "mcp>=0.9.0",
    "pandas>=2.0.0",
    "janome>=0.5.0",
    "spacy>=3.7.0",
    "en-core-web-sm @ https://github.com/explosion/spacy-models/...",
    "langdetect>=1.0.9",
    "wordcloud>=1.9.0",
    "plotly>=5.18.0",
    # ... 他の依存関係
]

[project.scripts]
survey-insight-mcp = "survey_insight.server:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.metadata]
allow-direct-references = true  # ← URLからの直接インストール許可

何が起こるか

1. uvx が GitHub から survey-insight-mcp をクローン
   → C:\Users\xxx\AppData\Local\uv\cache\git-v0\checkouts\{hash}\

2. pyproject.toml を読んで Python 3.10+ を確認
   → すでに 3.12.12 があるのでスキップ（初回は自動DL）

3. 依存パッケージを一括インストール
   → pandas, janome, spacy, wordcloud, plotly...
   → 全て wheels-v5/ にキャッシュ

4. survey-insight-mcp コマンドが利用可能に
   → Claude Code から MCP プロトコルで呼び出せる

5. 2回目以降は超高速起動（キャッシュ利用）

uv/uvx の圧倒的なメリット

1. ユーザー視点

✅ Python不要

「Pythonのインストール方法が分からない」→ 不要！
「環境変数PATHって何？」→ 設定不要！

✅ 1コマンドで完結

複雑な手順書不要
OS依存の違いを気にしなくてOK

✅ 自動アップデート

GitHubに新版をプッシュするだけ
ユーザーは再インストールするだけで最新版に

2. 開発者視点

✅ 配布が簡単

# これだけ！
1. GitHub にプッシュ
2. README に claude mcp add コマンドを記載

✅ 依存関係管理が楽

# pyproject.toml に書くだけで自動解決
dependencies = [
    "pandas>=2.0.0",
    "numpy>=1.24.0",
]

✅ バージョン管理が自動

# Pythonバージョンも自動管理
requires-python = ">=3.10"

✅ 開発環境も統一

# 開発時
uv venv              # 仮想環境作成（高速）
uv pip install -e .  # 開発モードインストール
uv run pytest        # テスト実行

# 本番（ユーザー）
uvx --from git+...   # 1コマンドで実行

3. パフォーマンス

速度比較（実測）

操作	pip	uv	高速化
依存解決	30秒	0.3秒	100倍
インストール	15秒	1.5秒	10倍
仮想環境作成	3秒	0.1秒	30倍

理由:

Rust製（メモリ安全 + 並列処理）
賢いキャッシング
最適化された依存解決アルゴリズム

実装ガイド：MCPサーバを uvx 対応にする

ステップ1: プロジェクト構成

my-mcp-server/
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── server.py       # MCPサーバ本体
│       └── mcp_server.py   # MCP実装
├── tests/
│   └── test_server.py
├── pyproject.toml          # ← 重要！
├── README.md
└── .gitignore

ステップ2: pyproject.toml 作成

[project]
name = "my-mcp-server"
version = "0.1.0"
description = "My awesome MCP server"
readme = "README.md"
requires-python = ">=3.10"
authors = [
    { name = "Your Name" }
]

dependencies = [
    "mcp>=0.9.0",
    # あなたの依存パッケージ
]

[project.scripts]
my-mcp-server = "my_package.server:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.ruff]
line-length = 127

ステップ3: server.py 実装

# src/my_package/server.py

import asyncio
from mcp.server.stdio import stdio_server
from .mcp_server import app

def main():
    """MCPサーバのエントリーポイント."""
    asyncio.run(run_server())

async def run_server():
    """MCPサーバを起動."""
    async with stdio_server() as (read_stream, write_stream):
        await app.run(
            read_stream,
            write_stream,
            app.create_initialization_options()
        )

if __name__ == "__main__":
    main()

ステップ4: ローカルテスト

# 開発環境セットアップ
uv venv
uv pip install -e .

# 動作確認
uv run my-mcp-server

# テスト実行
uv run pytest

ステップ5: GitHub にプッシュ

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/my-mcp-server.git
git push -u origin main

ステップ6: README に使い方を記載

# My MCP Server

## インストール

### 方法1: コマンドライン（Claude Code）

\`\`\`bash
claude mcp add --transport stdio my-mcp-server --scope user -- \\
  uvx --from git+https://github.com/username/my-mcp-server.git \\
  my-mcp-server
\`\`\`

Claude Code を再起動すれば使えます！

### 方法2: 設定ファイル（全MCPホスト対応）

#### Claude Code

\`~/.claude.json\` に追加：

\`\`\`json
{
  "mcpServers": {
    "my-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/username/my-mcp-server.git",
        "my-mcp-server"
      ]
    }
  }
}
\`\`\`

#### Gemini CLI

\`~/.gemini/settings.json\` に追加：

\`\`\`json
{
  "mcpServers": {
    "my-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/username/my-mcp-server.git",
        "my-mcp-server"
      ]
    }
  }
}
\`\`\`

#### Cline (VS Code)

VS Code の設定に追加：

\`\`\`json
{
  "cline.mcpServers": {
    "my-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/username/my-mcp-server.git",
        "my-mcp-server"
      ]
    }
  }
}
\`\`\`

設定後、MCPホストを再起動してください。

ステップ7: ユーザーが実行

パターンA: コマンドライン（Claude Code）

# ユーザー側（Pythonインストール不要！）
claude mcp add --transport stdio my-mcp-server --scope user -- \
  uvx --from git+https://github.com/username/my-mcp-server.git \
  my-mcp-server

# Claude Code を再起動
# → 自動的に動く！

パターンB: 設定ファイル（Claude Code / Gemini CLI / Cline）

# 1. 適切な設定ファイルを編集
# Claude Code: ~/.claude.json
# Gemini CLI: ~/.gemini/settings.json
# Cline: VS Code設定

# 2. JSON設定をコピペ（上記参照）

# 3. MCPホストを再起動
# → 自動的に動く！

トラブルシューティング

Q1. URLからのパッケージインストールでエラー

エラー:

ValueError: Dependency cannot be a direct reference unless
field `tool.hatch.metadata.allow-direct-references` is set to `true`

解決策:

# pyproject.toml に追加
[tool.hatch.metadata]
allow-direct-references = true

Q2. Pythonバージョンが合わない

エラー:

This package requires Python >=3.10

解決策:

# pyproject.toml で適切に指定
[project]
requires-python = ">=3.10"

uvx が自動的に適切なバージョンをダウンロードします。

Q3. キャッシュが古くて最新版が動かない

解決策:

# キャッシュクリア
uv cache clean

# 再インストール
claude mcp remove my-mcp-server
claude mcp add --transport stdio my-mcp-server --scope user -- \
  uvx --from git+https://github.com/username/my-mcp-server.git \
  my-mcp-server

ベストプラクティス

1. セマンティックバージョニング

[project]
version = "0.3.1"  # MAJOR.MINOR.PATCH

MAJOR: 互換性のない変更
MINOR: 後方互換性のある機能追加
PATCH: バグフィックス

2. 依存関係は明示的に

# 良い例
dependencies = [
    "mcp>=0.9.0",           # 最小バージョン指定
    "pandas>=2.0.0,<3.0",   # 範囲指定
]

# 避けるべき
dependencies = [
    "pandas",  # ← バージョン未指定（将来壊れる可能性）
]

3. 開発用依存関係は分離

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]

# 開発時のみインストール
uv pip install -e ".[dev]"

4. README にクイックスタートを必ず記載

## クイックスタート

### パターン1: コマンドライン（Claude Code推奨）

\`\`\`bash
claude mcp add --transport stdio my-server --scope user -- \
  uvx --from git+https://github.com/user/repo.git my-server
\`\`\`

### パターン2: 設定ファイル（Claude Code / Gemini CLI / Cline対応）

各MCPホストの設定ファイルに以下を追加:

**Claude Code**: `~/.claude.json` (macOS/Linux) / `%USERPROFILE%\.claude.json` (Windows)
**Gemini CLI**: `~/.gemini/settings.json` (macOS/Linux) / `%USERPROFILE%\.gemini\settings.json` (Windows)
**Cline**: VS Code設定の `cline.mcpServers`

\`\`\`json
{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/user/repo.git",
        "my-server"
      ]
    }
  }
}
\`\`\`

MCPホストを再起動して完了！

まとめ

uv/uvx を使うべき理由

ユーザーフレンドリー
- Python未インストールでもOK
- 1コマンドで完結
開発者にも優しい
- 配布が簡単（GitHub + uvx）
- 依存関係管理が楽
圧倒的に速い
- pip の 10～100倍高速
- キャッシュで2回目以降は爆速
クリーン
- システム環境を汚さない
- バージョン管理が自動

MCPサーバ開発のベストプラクティス

✅ pyproject.toml で依存関係を明示
✅ requires-python で Python バージョン指定
✅ GitHub でソース管理
✅ uvx で配布
✅ README にクイックスタート記載

参考リンク

uv公式: https://github.com/astral-sh/uv
MCP仕様: https://modelcontextprotocol.io/
実例（Survey Insight）: https://github.com/sinjorjob/survey-insight-mcp

Happy MCP Development with uv/uvx! ⚡

Accenture Japan (有志)

アクセンチュア株式会社に所属する社員有志による運営です。アクセンチュアの社員による様々な発信をまとめています。なお、投稿内容は社員個人の見解であり、所属する組織を代表するものではありません。

はじめに

TL;DR（結論）

従来の方法 vs uv/uvx

従来の方法（pip/venv）の課題

uv/uvx を使う方法

パターン1: コマンド一発（Claude Code推奨）

パターン2: 設定ファイル（Claude Code / Gemini CLI / Cline 対応）

uv/uvx とは？

uv

uvx

MCPサーバ配布の仕組み（完全図解）

全体アーキテクチャ

処理フロー（時系列）

ファイルシステム構造

uvx が管理するディレクトリ

キャッシュの再利用

pyproject.toml の重要性

最小構成

uvx の挙動

実例：Survey Insight MCP Server

配布方法

方法1: コマンドラインでインストール（Claude Code）

方法2: 設定ファイルで登録（全MCPホスト対応）

pyproject.toml（抜粋）

何が起こるか

uv/uvx の圧倒的なメリット

1. ユーザー視点

2. 開発者視点

3. パフォーマンス

実装ガイド：MCPサーバを uvx 対応にする

ステップ1: プロジェクト構成

ステップ2: pyproject.toml 作成

ステップ3: server.py 実装

ステップ4: ローカルテスト

ステップ5: GitHub にプッシュ

ステップ6: README に使い方を記載

ステップ7: ユーザーが実行

パターンA: コマンドライン（Claude Code）

パターンB: 設定ファイル（Claude Code / Gemini CLI / Cline）

トラブルシューティング

Q1. URLからのパッケージインストールでエラー

Q2. Pythonバージョンが合わない

Q3. キャッシュが古くて最新版が動かない

ベストプラクティス

1. セマンティックバージョニング

2. 依存関係は明示的に

3. 開発用依存関係は分離

4. README にクイックスタートを必ず記載

まとめ

uv/uvx を使うべき理由

MCPサーバ開発のベストプラクティス

参考リンク

Discussion