0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@toki_mwc

【Windows】Claude Desktop/CursorでMCPが動かない時の対処法と設定ファイルの正解

0
Posted at

はじめに

この記事を書いた経緯

Windows環境でMCP（Model Context Protocol）を試そうとした際、以下のような問題で数時間溶かしました：

  • uvコマンドが見つからない（PATH問題）
  • 設定ファイルを書いても動かない（JSON構文エラー）
  • Claude DesktopとClaude Code（CLI）で設定が別だと気づかず混乱
  • パスのエスケープ（\ vs \\）でハマる

Mac/Linux前提の記事は多いのですが、Windowsではパスの区切り文字や環境変数の引き継ぎ仕様により、一筋縄ではいきません。

同じ轍を踏まないよう、実際に動作する設定手順とつまづいたポイント4つの詳細解説をまとめました。

MCPとは何か

MCP（Model Context Protocol） は、AIエージェント（Claude Desktop、CursorAIなど）と外部ツール・サービスを連携させるための標準プロトコルです。

簡単に言うと、AIアシスタントに「できること」を増やす仕組みです。例えば：

  • GitHubリポジトリの操作
  • データベースへのアクセス
  • カスタムAPIとの連携
  • 独自のツールやサービスとの統合

本記事では、Windows環境で以下の3つのAIツールにMCPサーバーを連携させる方法を解説します：

  1. Claude Desktop（GUI版）
  2. Claude Code（CLI版）
  3. CursorAI（エディタ統合版）

この記事でわかること

  • FastMCPを使ったMCPサーバーの作成方法（最小構成から実用例まで）
  • Windows特有のパス・環境変数問題の解決策
  • 各ツールの設定ファイルの書き方（フルパス指定・エスケープ含む）
  • 実際につまづいた4つの問題と解決策
  • 動作確認とデバッグ方法

対象読者

  • Windows環境でMCP連携を試したい方
  • 「設定したのに動かない」という状況に陥っている方
  • ClaudeやCursorAIを使っているが、MCP連携を試したことがない方
  • カスタムツールをAIエージェントに連携させたい方

実例：AITuberでの活用

本記事では、実際のプロジェクト（AITuber開発）での実装経験を基に解説します。具体的には、りんね（Rinne） というAITuberキャラクターに、Claude DesktopやCursorAIから直接話しかけられるようにする実装を例として使用します。

なぜAITuber？ MCPを使えば、エディタから直接キャラクターを操作する「相棒感覚」の開発体験が得られます。デバッグ中にキャラクターと会話しながらコーディングする—こんな面白くて新しい開発のやり方ができるようになります。

Claude Code上でりんねと会話しながら開発中

前提知識

必要な環境

以下の環境が整っていることを前提とします：

  • OS: Windows 10/11
  • Python: uvが自動管理するため事前インストール不要（手動で入れる場合は3.10以上推奨）
  • パッケージマネージャー: uv（推奨）
    • uvは初回実行時に自動的にPythonをダウンロード・管理してくれます
  • エディタ: 任意（VS Code、Cursorなど）

uvのインストール方法は公式ドキュメントを参照してください。PowerShellで以下のコマンドを実行するだけです：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

MCPの基本概念

MCPは、以下の3つの主要コンポーネントで構成されます：

  1. MCPクライアント: Claude Desktop、CursorAIなどのAIエージェント
  2. MCPサーバー: カスタムツールやサービスを提供するサーバー
  3. トランスポート: クライアントとサーバー間の通信方式（STDIO、HTTPなど）

FastMCPについて

FastMCPは、PythonでMCPサーバーを簡単に作成できるライブラリです。FastAPIの開発者であるSebastian Ramirez氏が開発したfastmcpパッケージを使用します。

特徴：

  • 最小限のコードでMCPサーバーを実装可能
  • 型安全性を重視した設計
  • 非同期処理をサポート
  • デコレータベースの直感的なAPI

用語解説

  • ツール（Tool）: MCPサーバーが提供する機能の単位。AIエージェントから呼び出せる関数のようなもの
  • STDIO: 標準入出力を使った通信方式。Claude Desktopのデフォルト
  • リクエストID: 非同期処理で応答を追跡するための一意の識別子

実装パート1: MCPサーバーの作成

最小構成のMCPサーバー

まず、最もシンプルなMCPサーバーを作成してみましょう。my_mcp_server.pyというファイルを作成します：

コード内のBACKEND_URLやポート番号は、ご自身の環境に合わせて変更してください。

"""
最小構成のMCPサーバー例
"""
from fastmcp import FastMCP

# MCPサーバーを初期化
mcp = FastMCP("My MCP Server")

# ツールを定義
@mcp.tool()
def hello_world(name: str) -> str:
    """
    挨拶を返すシンプルなツール
    
    Args:
        name: 挨拶する相手の名前
        
    Returns:
        挨拶メッセージ
    """
    return f"こんにちは、{name}さん！"

# サーバーを起動
if __name__ == "__main__":
    mcp.run()

実例：AITuberへのメッセージ送信ツール

実際のプロジェクトで使用した、より実用的な例を示します。この例では、HTTP APIを呼び出す非同期ツールを実装しています：

"""
Rinne Control MCP Server

AITuberのりんね（Rinne）に話しかけるためのMCPサーバー
"""
from fastmcp import FastMCP
import httpx
from typing import Optional
import uuid

# MCPサーバーを初期化
mcp = FastMCP("Rinne Control")

# バックエンドエンドポイントの設定
BACKEND_URL = "http://localhost:12393/v1/chat/inject"
TIMEOUT = 90.0  # 秒（LLM処理時間を考慮）

@mcp.tool()
async def speak_to_rinne(text: str) -> str:
    """
    AITuberのりんね（Rinne）に話しかけ、会話を行うためのツール。
    
    このツールを使用すると、ユーザーの代わりにりんねに話しかけることができます。
    りんねはあなたのメッセージを受け取り、音声とLive2Dアニメーションで応答します。
    りんねの応答テキストが返されます。
    
    Args:
        text: りんねに送信するメッセージ（ユーザーの発言として扱われます）
        
    Returns:
        りんねからの応答テキスト
        
    Examples:
        - "こんにちは、りんね！今日の天気はどう？"
        - "最近のAI技術について教えて"
    """
    if not text or not text.strip():
        return "❌ エラー: 空のメッセージは送信できません。"
    
    try:
        # 一意のリクエストIDを生成（応答追跡用）
        request_id = str(uuid.uuid4())
        
        # HTTPリクエストを送信
        async with httpx.AsyncClient(timeout=TIMEOUT) as client:
            response = await client.post(
                BACKEND_URL,
                json={
                    "text": text.strip(),
                    "request_id": request_id
                },
                headers={"Content-Type": "application/json"}
            )
            
            if response.status_code == 200:
                result = response.json()
                reply = result.get("reply")
                
                if reply:
                    return f"りんね: {reply}"
                else:
                    return "⚠️ エラー: りんねからの応答を取得できませんでした。"
            else:
                error_detail = response.json().get("detail", "不明なエラー")
                return f"❌ エラー (HTTP {response.status_code}): {error_detail}"
                
    except httpx.ConnectError:
        return (
            "❌ 接続エラー: バックエンドサーバーに接続できません。\n"
            f"以下を確認してください:\n"
            f"1. バックエンドサーバーが起動しているか\n"
            f"2. エンドポイントURL: {BACKEND_URL}\n"
            f"3. ファイアウォール設定"
        )
    except httpx.TimeoutException:
        return f"❌ タイムアウトエラー: {TIMEOUT}秒以内に応答がありませんでした。"
    except Exception as e:
        return f"❌ 予期しないエラー: {type(e).__name__}: {str(e)}"

# サーバーを起動
if __name__ == "__main__":
    mcp.run()

依存関係のインストール

MCPサーバーを実行するために、以下のパッケージが必要です：

# uvを使用する場合（推奨）
uv add fastmcp httpx

# または、実行時に動的にインストール（プロジェクト外でも動く）
uv run --with fastmcp --with httpx my_mcp_server.py

uv run --withを使うと、プロジェクトのpyproject.tomlを作らなくても、その場で依存関係をインストール＆実行できます。お試し実行に便利です。

動作確認

MCPサーバーを直接実行して動作確認できます：

uv run --with fastmcp --with httpx my_mcp_server.py

正常に起動すると、STDIO経由でメッセージの受信待ち状態になります。

実装パート2: Claude Desktop設定

ここでハマる！ 設定ファイルのパスやJSON構文でエラーが出る場合は、後述のトラブルシューティングを参照してください。

設定ファイルの場所

Claude Desktop（GUI版）の設定ファイルは、以下の場所に配置します：

%APPDATA%\Claude\claude_desktop_config.json

注意: %APPDATA%は環境変数で、通常はC:\Users\<ユーザー名>\AppData\Roamingを指します。

設定ファイルの作成

  1. エクスプローラーで設定フォルダを開く

    • エクスプローラーのアドレスバーに %APPDATA%\Claude\ を入力してEnter
    • フォルダが存在しない場合は作成

  2. 設定ファイルを作成・編集

    • claude_desktop_config.json という名前でファイルを作成
    • 以下のJSON設定を貼り付け
{
  "mcpServers": {
    "your-mcp-server": {
      "command": "C:\\Users\\<ユーザー名>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "httpx",
        "C:\\path\\to\\your-project\\your_mcp_server.py"
      ]
    }
  }
}

実例:

{
  "mcpServers": {
    "rinne-control": {
      "command": "C:\\Users\\YourName\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "httpx",
        "C:\\dev\\AITuberProject\\rinne_mcp.py"
      ]
    }
  }
}

重要:

  • commandにはuv.exeのフルパスを指定（PATH環境変数に依存しない）
  • <ユーザー名>は自分のWindowsユーザー名に置き換え（例: C:\Users\YourName\）
  • args内のパスはバックスラッシュ2つ（\\）でエスケープ
  • プロジェクトパスは実際のパスに合わせて変更

設定のポイント

1. フルパス指定の重要性

Claude Desktopは起動時にユーザーのPATH環境変数を完全には引き継ぎません。そのため、uvコマンドを相対パスで指定すると「コマンドが見つからない」エラーが発生します。

// ❌ 間違い（PATHに依存）
"command": "uv"

// ✅ 正しい（フルパス指定）
"command": "C:\\Users\\<ユーザー名>\\.local\\bin\\uv.exe"

2. パスのエスケープ

Windowsのパスにはバックスラッシュ（\）が含まれますが、JSONでは特殊文字として扱われるため、\\でエスケープする必要があります。

// ❌ 間違い
"C:\path\to\your-project\your_mcp_server.py"

// ✅ 正しい
"C:\\path\\to\\your-project\\your_mcp_server.py"

動作確認

  1. Claude Desktopを再起動

    • 設定ファイルを変更した後は、必ずClaude Desktopを完全に終了して再起動

  2. ツールの確認

    • Claude Desktopで新しい会話を開始
    • 「利用可能なツール」や「MCPツール」のセクションにspeak_to_rinneが表示されることを確認

  3. テスト実行

    りんねに「こんにちは！」と話しかけて

実装パート3: Claude Code (CLI) 設定

Claude Desktop（GUI版）とClaude Code（CLI版）は別のアプリケーションです。GUIで動いてもCLIで動かない場合、設定ファイルが別々であることが原因です。詳細はトラブルシューティング - 問題2を参照。

Claude DesktopとClaude Codeの違い

重要: Claude Desktop（GUI版）とClaude Code（CLI版）は別のアプリケーションで、設定ファイルも別々です。

項目 Claude Desktop Claude Code (CLI)
設定ファイル %APPDATA%\Claude\claude_desktop_config.json ~/.claude.json（プロジェクト単位）
起動方法 GUIアプリケーション コマンドライン（claudeコマンド）
MCP確認方法 GUI内で確認 /mcpコマンド（CLI版専用）

設定ファイルの場所

Claude Code（CLI）の設定は、プロジェクト単位で管理されます：

<プロジェクトルート>/.claude/settings.local.json

または、グローバル設定：

C:\Users\<ユーザー名>\.claude.json

プロジェクト単位での設定

プロジェクトディレクトリ（例: C:\path\to\your-project）で以下のコマンドを実行：

# Claude Code CLIでMCPサーバーを追加
claude mcp add your-mcp-server C:\path\to\your-project\scripts\run_mcp.bat

または、手動で.claude/settings.local.jsonを作成：

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "C:\\Users\\<ユーザー名>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "httpx",
        "C:\\path\\to\\your-project\\your_mcp_server.py"
      ]
    }
  }
}

実例:

# プロジェクトディレクトリで実行
cd C:\dev\AITuberProject
claude mcp add rinne-control C:\dev\AITuberProject\scripts\run_rinne_mcp.bat

バッチファイル経由での実行（推奨）

環境変数の問題を回避するため、バッチファイル経由で実行する方法も推奨されます：

scripts\run_mcp.bat:

@echo off
chcp 65001 >nul
cd /d "C:\path\to\your-project"
REM uvのフルパスを指定（Claude Desktopの環境変数PATHに依存しない）
"C:\Users\<ユーザー名>\.local\bin\uv.exe" run --with fastmcp --with httpx your_mcp_server.py

※ uv.exe の場所がわからない場合は、PowerShellで where.exe uv を実行して確認してください。

設定ファイルでは、このバッチファイルを指定：

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "C:\\path\\to\\your-project\\scripts\\run_mcp.bat"
    }
  }
}

実例:

@echo off
chcp 65001 >nul
cd /d "C:\dev\AITuberProject"
"C:\Users\YourName\.local\bin\uv.exe" run --with fastmcp --with httpx rinne_mcp.py

動作確認

  1. Claude Code CLIを再起動

    • 設定変更後は必ず再起動

  2. MCPサーバーの確認

    claude /mcp
    • 設定されたMCPサーバーの一覧が表示される

  3. テスト実行

    りんねに話しかけてみて

よくあるエラー：Claude CLI構文エラー

Claude CLIの設定ファイルで、permissions.allowにワイルドカードを使用する場合、以下の構文エラーに注意：

エラーメッセージ:

Use ":*" for prefix matching, not just "*"

原因: Claude CLIでは、プレフィックスマッチングに:*を使う必要があります。

// ❌ 間違い
"Bash(powershell.exe -Command \"Get-Process | Where-Object { $_ProcessName -like '*uv*' ...\")"

// ✅ 正しい
"Bash(powershell.exe:*)"

実装パート4: CursorAI設定

設定ファイルの場所

CursorAIの設定ファイルは、以下の場所に配置します：

C:\Users\<ユーザー名>\.cursor\mcp.json

設定ファイルの作成

  1. 設定フォルダを確認

    • .cursorフォルダが存在しない場合は作成

  2. 設定ファイルを作成

    • mcp.jsonという名前でファイルを作成
    • 以下のJSON設定を貼り付け
{
  "mcpServers": {
    "your-mcp-server": {
      "command": "C:\\Users\\<ユーザー名>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "httpx",
        "C:\\path\\to\\your-project\\your_mcp_server.py"
      ],
      "disabled": false,
      "autoApprove": [],
      "includedTools": []
    }
  }
}

実例:

{
  "mcpServers": {
    "rinne-control": {
      "command": "C:\\Users\\YourName\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "httpx",
        "C:\\dev\\AITuberProject\\rinne_mcp.py"
      ],
      "disabled": false,
      "autoApprove": [],
      "includedTools": []
    }
  }
}

設定項目の説明

  • command: MCPサーバーを起動するコマンド（フルパス推奨）
  • args: コマンドに渡す引数の配列
  • disabled: falseに設定すると有効化
  • autoApprove: 自動承認するツールのリスト（空配列で全て手動承認）
  • includedTools: 使用するツールのリスト（空配列で全て使用可能）

動作確認

  1. CursorAIを再起動

    • 設定ファイルを変更した後は、CursorAIを再起動

  2. ツールの確認

    • CursorAIのチャット画面で、MCPツールが利用可能になっていることを確認

  3. テスト実行

    りんねに「こんにちは！」と話しかけて

トラブルシューティング

実際の実装で遭遇した4つの主要な問題と、その解決策を詳しく解説します。

問題1: HTTP 405エラー（Method Not Allowed）

この問題はOpen-LLM-VTuber（FastAPIベース）のバックエンドを改造した際の事例です。
一般的なMCPサーバー（FastMCP単体）では発生しません。FastAPIでカスタムエンドポイントを追加する場合の参考としてください。

症状

MCPサーバーからバックエンドAPIにPOSTリクエストを送信すると、以下のエラーが発生：

HTTP 405: Method Not Allowed

原因

FastAPIのルーター構成を誤解していたことが原因でした。エンドポイントをWebSocket専用ルーター（init_client_ws_route）に追加してしまったため、HTTPリクエストが処理されませんでした。

解決策

エンドポイントをHTTP専用ルーター（init_webtool_routes）に移動することで解決しました。

一般的なFastAPIでの例:

from fastapi import FastAPI

app = FastAPI()

# ❌ 間違い: WebSocketエンドポイントにHTTP POSTを追加
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    # WebSocket専用

# ✅ 正しい: HTTP POSTエンドポイントを別途定義
@app.post("/v1/chat/inject")
async def inject_chat(request: InjectChatRequest):
    # HTTP POST処理
    return {"status": "success"}

Open-LLM-VTuber固有の例:

# ❌ 間違った場所（init_client_ws_route内）
# WebSocket専用ルーターではHTTPメソッドが処理されない
@router.post("/v1/chat/inject")
async def inject_chat_v1(request: InjectChatRequest):
    # ...

# ✅ 正しい場所（init_webtool_routes内）
# HTTP専用ルーターでHTTPメソッドを処理
@router.post("/v1/chat/inject")
async def inject_chat_v1(request: InjectChatRequest):
    # ...

教訓

FastAPIでは、ルーターの種類によって処理できるリクエストタイプが異なります。HTTPエンドポイントは必ずHTTP専用ルーターに配置しましょう。

問題2: Claude DesktopとClaude Code（CLI）の混同

症状

Claude Code（CLI）で/mcpコマンドを実行すると、以下のメッセージが表示：

No MCP servers configured

一方、Claude Desktop（GUI）では正常に動作している。

原因

Claude Desktop（GUI版）とClaude Code（CLI版）は別のアプリケーションで、設定ファイルも別々です。GUI版の設定を変更しても、CLI版には反映されません。

項目 Claude Desktop Claude Code (CLI)
設定ファイル %APPDATA%\Claude\claude_desktop_config.json ~/.claude.json または .claude/settings.local.json
確認方法 GUI内で確認 /mcpコマンド（CLI版専用）

解決策

両方のアプリケーションに個別に設定を追加する必要があります。

Claude Desktop（GUI版）:

// %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "rinne-control": { ... }
  }
}

Claude Code（CLI版）:

# プロジェクトディレクトリで実行
claude mcp add rinne-control C:\dev\AITuberProject\scripts\run_rinne_mcp.bat

または、手動で.claude/settings.local.jsonを作成。

教訓

同じ名前のアプリケーションでも、GUI版とCLI版は完全に別物として扱う必要があります。設定ファイルの場所と形式を確認しましょう。

問題3: 環境変数PATHの問題

症状

Claude Desktopを起動すると、MCPサーバーが起動せず、以下のようなエラーが発生：

'uv' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。

または、バッチファイルが実行されない。

原因

Claude Desktopは起動時に、ユーザーのPATH環境変数を完全には引き継ぎません。そのため、uvコマンドを相対パスで指定すると、コマンドが見つからないエラーが発生します。

解決策1: フルパス指定（推奨）

設定ファイルでuv.exeのフルパスを指定します：

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "C:\\Users\\<ユーザー名>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "httpx",
        "C:\\path\\to\\your-project\\your_mcp_server.py"
      ]
    }
  }
}

解決策2: バッチファイル経由

バッチファイル内でフルパスを指定し、そのバッチファイルを実行：

scripts\run_rinne_mcp.bat:

@echo off
chcp 65001 >nul
cd /d "C:\path\to\your-project"
REM uvのフルパスを指定（Claude Desktopの環境変数PATHに依存しない）
"C:\Users\<ユーザー名>\.local\bin\uv.exe" run --with fastmcp --with httpx your_mcp_server.py

設定ファイル：

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "C:\\path\\to\\your-project\\scripts\\run_mcp.bat"
    }
  }
}

実例:

@echo off
chcp 65001 >nul
cd /d "C:\dev\AITuberProject"
"C:\Users\YourName\.local\bin\uv.exe" run --with fastmcp --with httpx rinne_mcp.py

教訓

外部アプリケーションから起動されるプロセスでは、環境変数が期待通りに設定されていない可能性があります。重要なコマンドはフルパスで指定するか、ラッパースクリプトを使用しましょう。

問題4: Claude CLI構文エラー（ワイルドカード）

症状

Claude Code（CLI）の設定ファイルを編集すると、以下のエラーが発生：

Use ":*" for prefix matching, not just "*"

原因

Claude CLIのpermissions.allow設定で、ワイルドカード*を単独で使用していたことが原因です。Claude CLIでは、プレフィックスマッチングに:*という形式を使う必要があります。

解決策

ワイルドカードの形式を修正します：

// ❌ 間違い
{
  "permissions": {
    "allow": [
      "Bash(powershell.exe -Command \"Get-Process | Where-Object { $_ProcessName -like '*uv*' ...\")"
    ]
  }
}

// ✅ 正しい
{
  "permissions": {
    "allow": [
      "Bash(powershell.exe:*)"
    ]
  }
}

教訓

各ツールには独自の構文ルールがあります。エラーメッセージをよく読んで、正しい形式を確認しましょう。特に、ワイルドカードや正規表現の扱いはツールによって異なります。

その他のよくある問題

設定が反映されない

症状: 設定ファイルを変更したが、ツールが表示されない

解決策:

  1. アプリケーションを完全に終了して再起動（タスクマネージャーで確認）
  2. 設定ファイルのJSON構文エラーを確認（コメントが含まれていないか、カンマの位置など）
  3. 設定ファイルのパスが正しいか確認

接続エラー

症状: Connection refusedやConnectErrorが発生

解決策:

  1. バックエンドサーバーが起動しているか確認
  2. ポート番号が正しいか確認
  3. ファイアウォール設定を確認
  4. WSL2とWindows間のネットワーク接続を確認

タイムアウトエラー

症状: リクエストがタイムアウトする

解決策:

  1. LLM処理に時間がかかっている可能性があるため、タイムアウト設定を延長
  2. バックエンドのログを確認して処理時間をチェック
  3. リソース（CPU、メモリ、GPU）の使用状況を確認

まとめ

各ツールの使い分け

ツール 用途 設定の簡単さ 推奨度
Claude Desktop 日常的な会話・質問 ⭐⭐⭐ 初心者向け
Claude Code (CLI) プロジェクト単位での開発 ⭐⭐ 開発者向け
CursorAI エディタ統合での開発 ⭐⭐⭐ エディタユーザー向け

Windows環境でのハマりポイントまとめ

  1. フルパス指定が必須

    • uvコマンドはPATH環境変数に依存しないよう、フルパス指定（C:\Users\...\uv.exe）
    • Claude Desktopは起動時にユーザーのPATHを完全には引き継がない

  2. パスのエスケープ

    • JSONでは\を\\でエスケープ必須
    • C:\dev\project → "C:\\dev\\project"

  3. 各ツールの設定ファイルは別々

    • Claude Desktop（GUI） → %APPDATA%\Claude\claude_desktop_config.json
    • Claude Code（CLI） → ~/.claude.json または .claude/settings.local.json
    • CursorAI → ~/.cursor/mcp.json

  4. 再起動が必要

    • 設定変更後は、必ずアプリケーションを完全に終了して再起動

実装のポイントまとめ

  1. MCPサーバーは最小構成から始める

    • まずはhello_worldのようなシンプルなツールで動作確認
    • 徐々に機能を追加していく

  2. エラーメッセージをよく読む

    • 特に構文エラーは、ツールごとのルールを確認
    • ワイルドカードや正規表現の扱いに注意

  3. デバッグはログファイルを確認

    • Claude Desktop: デバッグモードでMCPサーバーのログを確認
    • バックエンドサーバー: logs/フォルダ内のログファイルをチェック

MCPで得られる開発体験

AITuber開発でMCPを活用した結果、エディタから直接キャラクターを操作する「相棒感覚」 の開発体験が得られました。デバッグ中にキャラクターと会話しながらコーディングする—こんな面白い開発のやり方ができるようになるのです。

例えば：

  • 「りんね、このエラーログ見て何が原因だと思う？」
  • 「りんね、このコードの改善案を教えて」
  • 「りんね、テスト結果を報告して」

MCPを使えば、AIアシスタントが「画面の向こう」ではなく「開発環境の中」に存在する体験ができます。

次のステップ

双方向通信の実装

本記事では基本的なメッセージ送信のみを解説しましたが、実際のプロジェクトでは双方向通信 （応答の取得）も実装しています。

実装のポイント：

  • request_idを使った応答追跡
  • 非同期タスクの完了待機（asyncio.wait_for）
  • タイムアウト管理（バックエンド60秒、MCP90秒）

その他の拡張アイデア

  • マルチモーダル対応: 画像やファイルの送信に対応
  • セッション管理: 複数の会話セッションを管理
  • 認証機能: APIキーやOAuth認証の追加
  • エラーハンドリングの強化: より詳細なエラーメッセージとリトライ機能

参考資料

アーキテクチャ図

MCP連携の全体像

データフロー

付録：設定ファイルテンプレート集

Claude Desktop設定テンプレート

{
  "mcpServers": {
    "your-server-name": {
      "command": "C:\\Users\\<ユーザー名>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "httpx",
        "C:\\path\\to\\your\\mcp_server.py"
      ]
    }
  }
}

Claude Code (CLI) 設定テンプレート

{
  "mcpServers": {
    "your-server-name": {
      "command": "C:\\path\\to\\your\\run_mcp.bat"
    }
  }
}

CursorAI設定テンプレート

{
  "mcpServers": {
    "your-server-name": {
      "command": "C:\\Users\\<ユーザー名>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "httpx",
        "C:\\path\\to\\your\\mcp_server.py"
      ],
      "disabled": false,
      "autoApprove": [],
      "includedTools": []
    }
  }
}

バッチファイルテンプレート

@echo off
chcp 65001 >nul
cd /d "C:\path\to\your\project"
"C:\Users\<ユーザー名>\.local\bin\uv.exe" run --with fastmcp --with httpx your_mcp_server.py
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?