Claude MCPサーバーをローカル環境で構築・設定する実践ガイド

本記事では、Claude Model Context Protocol（MCP）サーバーをローカル環境にセットアップし、カスタムツールを連携させる手順を解説します。実装例を交えて、実務で即座に活用できる設定方法をお伝えします。

Claude MCPサーバーとは

Claude MCPサーバーは、Anthropic社が提供するプロトコルで、ClaudeをアシスタントAPIとして動作させ、外部ツールやリソースにアクセスさせる仕組みです。従来のプラグイン形式ではなく、スタンドアロンサーバーとして独立して動作し、ローカル環境やクラウド上で柔軟に展開できます。

MCPサーバーを導入することで、Claude自体がファイルシステム、データベース、APIエンドポイントに直接アクセス可能になり、より高度な自動化タスクの実行が容易になります。

前提条件と動作環境

本記事の検証環境：

• macOS 14 / Ubuntu 22.04（Linux）
• Python 3.10以上
• Node.js 18以上（TypeScript例の場合）
• Claude API 2025-01以上
• pip / npm パッケージマネージャー

MCPサーバーのセットアップ手順

1. MCPサーバーランタイムのインストール

まず、MCPサーバーを実行するためのランタイムをインストールします。Pythonを使用する場合は以下のコマンドで必要なパッケージを導入してください。

# MCPサーバー用の基本パッケージをインストール
pip install mcp anthropic

# オプション：型チェックやテストのための追加ツール
pip install pytest pydantic

TypeScriptを使用する場合は、以下のセットアップを実行します。

# 新規プロジェクトディレクトリを作成
mkdir mcp-server
cd mcp-server

# Node.jsプロジェクトを初期化
npm init -y

# 必要なパッケージをインストール
npm install @anthropic-ai/mcp axios express

2. シンプルなMCPサーバーの実装例

それでは、実際に動作するMCPサーバーを実装してみましょう。以下はファイル操作ツールを備えたPython実装例です。

#!/usr/bin/env python3
"""
シンプルなMCPサーバー実装例
ファイル読み込み・書き込みツールを提供
"""

from mcp.server import Server
from mcp.types import Tool, TextContent
import json
import os

# MCPサーバーのインスタンスを作成
server = Server("file-tools-server")

# ツール定義：ファイル内容を読み込む
read_file_tool = Tool(
    name="read_file",
    description="指定されたファイルの内容を読み込みます",
    inputSchema={
        "type": "object",
        "properties": {
            "file_path": {
                "type": "string",
                "description": "読み込むファイルの相対パス"
            }
        },
        "required": ["file_path"]
    }
)

# ツール定義：ファイルに内容を書き込む
write_file_tool = Tool(
    name="write_file",
    description="指定されたファイルに内容を書き込みます",
    inputSchema={
        "type": "object",
        "properties": {
            "file_path": {
                "type": "string",
                "description": "書き込むファイルの相対パス"
            },
            "content": {
                "type": "string",
                "description": "書き込む内容"
            }
        },
        "required": ["file_path", "content"]
    }
)

# ツール実装：ファイル読み込み
@server.call_tool("read_file")
def read_file(file_path: str):
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            content = f.read()
        return [TextContent(type="text", text=content)]
    except FileNotFoundError:
        return [TextContent(type="text", text=f"エラー: ファイルが見つかりません: {file_path}")]
    except Exception as e:
        return [TextContent(type="text", text=f"エラー: {str(e)}")]

# ツール実装：ファイル書き込み
@server.call_tool("write_file")
def write_file(file_path: str, content: str):
    try:
        # ディレクトリが存在しない場合は作成
        os.makedirs(os.path.dirname(file_path) or ".", exist_ok=True)
        
        with open(file_path, 'w', encoding='utf-8') as f:
            f.write(content)
        return [TextContent(type="text", text=f"成功: {file_path} に書き込みました")]
    except Exception as e:
        return [TextContent(type="text", text=f"エラー: {str(e)}")]

# サーバーにツールを登録
server.register_tool(read_file_tool)
server.register_tool(write_file_tool)

if __name__ == "__main__":
    # MCPサーバーを標準入出力で起動
    import sys
    server.run(sys.stdin.buffer, sys.stdout.buffer)

3. MCPサーバーの実行と接続設定

実装したMCPサーバーをClaudeから利用するには、設定ファイルで接続情報を定義します。ユーザーのホームディレクトリに.claude/claude_desktop_config.jsonファイルを作成してください。

{
  "mcpServers": {
    "file-tools": {
      "command": "python3",
      "args": ["/path/to/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/project"
      }
    }
  }
}

/path/to/mcp_server.pyは、上記で作成したMCPサーバースクリプトの絶対パスに置き換えてください。

実践的な活用例：データベースクエリツール

より実務的な例として、SQLiteデータベースに対するクエリ実行ツールを実装してみます。

#!/usr/bin/env python3
"""
MCPサーバー実装例：SQLiteデータベース操作
"""

from mcp.server import Server
from mcp.types import Tool, TextContent
import sqlite3
import json

server = Server("sqlite-tools-server")

# ツール定義：SQLクエリを実行
query_tool = Tool(
    name="execute_query",
    description="SQLiteデータベースに対してSQLクエリを実行します",
    inputSchema={
        "type": "object",
        "properties": {
            "db_path": {
                "type": "string",
                "description": "SQLiteデータベースファイルのパス"
            },
            "query": {
                "type": "string",
                "description": "実行するSQLクエリ"
            }
        },
        "required": ["db_path", "query"]
    }
)

@server.call_tool("execute_query")
def execute_query(db_path: str, query: str):
    try:
        # セキュリティ対策：SELECT文のみ許可（簡易版）
        if not query.strip().upper().startswith("SELECT"):
            return [TextContent(
                type="text",
                text="セキュリティ上の理由により、SELECT文のみ実行可能です"
            )]
        
        conn = sqlite3.connect(db_path)
        conn.row_factory = sqlite3.Row
        cursor = conn.cursor()
        cursor.execute(query)
        
        rows = cursor.fetchall()
        result = [dict(row) for row in rows]
        
        conn.close()
        return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False, indent=2))]
    
    except sqlite3.DatabaseError as e:
        return [TextContent(type="text", text=f"データベースエラー: {str(e)}")]
    except Exception as e:
        return [TextContent(type="text", text=f"エラー: {str(e)}")]

server.register_tool(query_tool)

if __name__ == "__main__":
    import sys
    server.run(sys.stdin.buffer, sys.stdout.buffer)

よくあるハマりポイントと解決策

問題1: MCPサーバーが起動しない

原因としては、Pythonパスの不一致やインポートエラーが考えられます。以下の対策を試してください。

• python3 -c "import mcp"でモジュールが正しくインストールされているか確認
• 設定ファイルのcommandフィールドが正しいPythonインタプリタを指定しているか確認
• スクリプトファイルに実行権限があるか確認：chmod +x mcp_server.py

問題2: Claudeがツールを認識しない

ツール登録のタイミングに問題がある可能性があります。server.register_tool()はサーバー起動前に全ツールを登録してください。また、ツール名は英数字とアンダースコアのみを使用してください。

問題3: ファイルパスエラーが発生

相対パスと絶対パスの混在が原因の場合があります。設定ファイルには絶対パスを指定し、ツール実装内ではos.path.abspath()で正規化することをお勧めします。

セキュリティ設定のベストプラクティス

MCPサーバーがローカル環境で動作する場合でも、セキュリティ対策は重要です。以下のガイドラインに従ってください。

• 入力検証：ユーザー入力を必ず検証し、SQLインジェクションやパストラバーサル攻撃を防ぐ
• 権限管理：データベースへのアクセス権限を最小限に制限
• エラーメッセージ：本番環境では詳細なエラー情報を非公開にする
• ログ記録：すべてのクエリ実行をログに記録し、監査可能な状態を保つ

MCPサーバーの使い分け：いつ使うべきか、使うべきでないか

MCPサーバーの使用に適した場面

• Claudeがローカルファイルシステムやデータベースにアクセスする必要がある場合
• 複雑なビジネスロジックをツール化して再利用したい場合
• 複数のClaudeインスタンス間でツールを共有したい場合

MCPサーバーの使用が不適切な場面

• 軽微なテキスト処理のみが必要な場合（直接Claudeのシステムプロンプトで対応可能）
• レイテンシが厳しい場合（プロセス間通信のオーバーヘッドあり）
• 一度きりの簡単なタスク（設定のコストが見合わない）

類似ツールとして、LangChainのツール定義やOpenAI Function Callingという選択肢もあります。ただしMCPサーバーは、独立したプロセスとして動作し、Claudeと密結合しない利点があり、複雑なシステム構築に適しています。

デバッグとトラブルシューティング

MCPサーバーが期待通りに動作しない場合は、以下の手順でデバッグしてください。

# ローカルでスタンドアロンテスト
python3 -m mcp.cli.server /path/to/mcp_server.py

# 詳細なログを有効化（環境変数で指定）
export MCP_DEBUG=1
python3 /path/to/mcp_server.py

# ツール実装を個別に単体テスト
# pytest を使用してテストケースを作成
import pytest
from mcp_server import execute_query

def test_execute_query():
    result = execute_query(":memory:", "SELECT 1 as test_column")
    assert result is not None

まとめ

• MCPサーバーとは：Claudeに外部ツール機能を提供するスタンドアロンサーバー
• セットアップの最小構成：Pyth