MCP（Model Context Protocol）サーバー構築ガイド¶

┌─────────────────────────────────────────┐
│          MCP Host（AIアプリケーション）       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │MCP Client│ │MCP Client│ │MCP Client│ │
│  │    1     │ │    2     │ │    3     │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼────────────┼────────────┼────────┘
        │            │            │
   ┌────▼────┐  ┌────▼────┐ ┌────▼────┐
   │MCP Server│ │MCP Server│ │MCP Server│
   │  A(Local)│ │  B(Local)│ │ C(Remote)│
   └─────────┘  └─────────┘ └─────────┘

{
  "name": "get_weather",
  "title": "Weather Information Provider",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or zip code"
      }
    },
    "required": ["location"]
  }
}

{
  "uri": "file:///project/src/main.rs",
  "name": "main.rs",
  "title": "Rust Software Application Main File",
  "description": "Primary application entry point",
  "mimeType": "text/x-rust"
}

{
  "name": "code_review",
  "title": "Request Code Review",
  "description": "Asks the LLM to analyze code quality and suggest improvements",
  "arguments": [
    {
      "name": "code",
      "description": "The code to review",
      "required": true
    }
  ]
}

# uvをインストール（パッケージマネージャー）
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# プロジェクト作成
uv init my-mcp-server
cd my-mcp-server

# 仮想環境作成・有効化
uv venv
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

# 依存関係インストール
uv add "mcp[cli]" httpx

# hello_server.py
from mcp.server.fastmcp import FastMCP

# FastMCPサーバーを初期化
mcp = FastMCP("hello")

@mcp.tool()
async def hello(name: str) -> str:
    """挨拶を返すツール。

    Args:
        name: 挨拶する相手の名前
    """
    return f"こんにちは、{name}さん！"

@mcp.resource("greeting://{name}")
async def get_greeting(name: str) -> str:
    """名前に基づく挨拶リソース。"""
    return f"{name}さんへの挨拶メッセージです。"

@mcp.prompt()
async def review_code(code: str) -> str:
    """コードレビュー用プロンプト。"""
    return f"以下のコードをレビューしてください:\n\n{code}"

def main():
    mcp.run(transport="stdio")

if __name__ == "__main__":
    main()

# weather.py
from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# FastMCPサーバーを初期化
mcp = FastMCP("weather")

# 定数
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"


async def make_nws_request(url: str) -> dict[str, Any] | None:
    """NWS APIへのリクエスト（エラーハンドリング付き）。"""
    headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None


def format_alert(feature: dict) -> str:
    """アラート情報をフォーマット。"""
    props = feature["properties"]
    return f"""
Event: {props.get("event", "Unknown")}
Area: {props.get("areaDesc", "Unknown")}
Severity: {props.get("severity", "Unknown")}
Description: {props.get("description", "No description available")}
Instructions: {props.get("instruction", "No specific instructions provided")}
"""


@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)

    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."

    if not data["features"]:
        return "No active alerts for this state."

    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)


@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get weather forecast for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # まずforecastグリッドエンドポイントを取得
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "Unable to fetch forecast data for this location."

    # pointsレスポンスからforecast URLを取得
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "Unable to fetch detailed forecast."

    # 期間をフォーマット
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # 次の5期間のみ表示
        forecast = f"""
{period["name"]}:
Temperature: {period["temperature"]}°{period["temperatureUnit"]}
Wind: {period["windSpeed"]} {period["windDirection"]}
Forecast: {period["detailedForecast"]}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)


def main():
    mcp.run(transport="stdio")


if __name__ == "__main__":
    main()

# ツール定義 -- LLMが呼び出せる関数
@mcp.tool()
async def my_tool(param: str) -> str:
    """ツールの説明（docstringが自動的にdescriptionになる）。

    Args:
        param: パラメータの説明（型ヒントからスキーマが自動生成）
    """
    return "結果"

# リソース定義 -- コンテキストデータの提供
@mcp.resource("myapp://config")
async def get_config() -> str:
    """設定情報を返すリソース。"""
    return "config data"

# リソーステンプレート -- パラメータ化されたリソース
@mcp.resource("myapp://users/{user_id}")
async def get_user(user_id: str) -> str:
    """ユーザー情報リソース。"""
    return f"User: {user_id}"

# プロンプト定義 -- 再利用可能なテンプレート
@mcp.prompt()
async def analyze(topic: str) -> str:
    """分析用プロンプト。"""
    return f"{topic}について詳しく分析してください。"

import sys
import logging

# NG: stdoutに書き込む
print("Processing request")

# OK: stderrに書き込む
print("Processing request", file=sys.stderr)

# OK: loggingモジュールを使用
logging.info("Processing request")

# Node.js 16以上が必要
node --version
npm --version

# プロジェクト作成
mkdir my-mcp-server
cd my-mcp-server
npm init -y

# 依存関係インストール
npm install @modelcontextprotocol/sdk zod@3
npm install -D @types/node typescript

# ソースディレクトリ作成
mkdir src

{
  "type": "module",
  "bin": {
    "my-mcp-server": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && chmod 755 build/index.js"
  },
  "files": ["build"]
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "hello",
  version: "1.0.0",
});

// ツール登録
server.registerTool(
  "hello",
  {
    description: "挨拶を返すツール",
    inputSchema: {
      name: z.string().describe("挨拶する相手の名前"),
    },
  },
  async ({ name }) => {
    return {
      content: [
        {
          type: "text",
          text: `こんにちは、${name}さん！`,
        },
      ],
    };
  },
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Hello MCP Server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const NWS_API_BASE = "https://api.weather.gov";
const USER_AGENT = "weather-app/1.0";

const server = new McpServer({
  name: "weather",
  version: "1.0.0",
});

// ヘルパー関数: NWS APIリクエスト
async function makeNWSRequest<T>(url: string): Promise<T | null> {
  const headers = {
    "User-Agent": USER_AGENT,
    Accept: "application/geo+json",
  };

  try {
    const response = await fetch(url, { headers });
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return (await response.json()) as T;
  } catch (error) {
    console.error("Error making NWS request:", error);
    return null;
  }
}

interface AlertFeature {
  properties: {
    event?: string;
    areaDesc?: string;
    severity?: string;
    status?: string;
    headline?: string;
  };
}

interface AlertsResponse {
  features: AlertFeature[];
}

interface PointsResponse {
  properties: {
    forecast?: string;
  };
}

interface ForecastPeriod {
  name?: string;
  temperature?: number;
  temperatureUnit?: string;
  windSpeed?: string;
  windDirection?: string;
  shortForecast?: string;
}

interface ForecastResponse {
  properties: {
    periods: ForecastPeriod[];
  };
}

function formatAlert(feature: AlertFeature): string {
  const props = feature.properties;
  return [
    `Event: ${props.event || "Unknown"}`,
    `Area: ${props.areaDesc || "Unknown"}`,
    `Severity: ${props.severity || "Unknown"}`,
    `Status: ${props.status || "Unknown"}`,
    `Headline: ${props.headline || "No headline"}`,
    "---",
  ].join("\n");
}

// ツール登録: 天気アラート取得
server.registerTool(
  "get_alerts",
  {
    description: "Get weather alerts for a state",
    inputSchema: {
      state: z
        .string()
        .length(2)
        .describe("Two-letter state code (e.g. CA, NY)"),
    },
  },
  async ({ state }) => {
    const stateCode = state.toUpperCase();
    const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;
    const alertsData = await makeNWSRequest<AlertsResponse>(alertsUrl);

    if (!alertsData) {
      return {
        content: [{ type: "text" as const, text: "Failed to retrieve alerts data" }],
      };
    }

    const features = alertsData.features || [];
    if (features.length === 0) {
      return {
        content: [{ type: "text" as const, text: `No active alerts for ${stateCode}` }],
      };
    }

    const formattedAlerts = features.map(formatAlert);
    return {
      content: [
        {
          type: "text" as const,
          text: `Active alerts for ${stateCode}:\n\n${formattedAlerts.join("\n")}`,
        },
      ],
    };
  },
);

// ツール登録: 天気予報取得
server.registerTool(
  "get_forecast",
  {
    description: "Get weather forecast for a location",
    inputSchema: {
      latitude: z.number().min(-90).max(90).describe("Latitude of the location"),
      longitude: z.number().min(-180).max(180).describe("Longitude of the location"),
    },
  },
  async ({ latitude, longitude }) => {
    const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;
    const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);

    if (!pointsData) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}.`,
          },
        ],
      };
    }

    const forecastUrl = pointsData.properties?.forecast;
    if (!forecastUrl) {
      return {
        content: [{ type: "text" as const, text: "Failed to get forecast URL" }],
      };
    }

    const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
    if (!forecastData) {
      return {
        content: [{ type: "text" as const, text: "Failed to retrieve forecast data" }],
      };
    }

    const periods = forecastData.properties?.periods || [];
    const formattedForecast = periods.map((period: ForecastPeriod) =>
      [
        `${period.name || "Unknown"}:`,
        `Temperature: ${period.temperature || "Unknown"}°${period.temperatureUnit || "F"}`,
        `Wind: ${period.windSpeed || "Unknown"} ${period.windDirection || ""}`,
        `${period.shortForecast || "No forecast available"}`,
        "---",
      ].join("\n"),
    );

    return {
      content: [
        {
          type: "text" as const,
          text: `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join("\n")}`,
        },
      ],
    };
  },
);

// サーバー起動
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

# ビルド
npm run build

# 実行
node build/index.js

// NG: stdoutに書き込む
console.log("Server started");

// OK: stderrに書き込む
console.error("Server started");

# 基本的な使い方
npx @modelcontextprotocol/inspector <command>

# npmパッケージのサーバーを検査
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /Users/username/Desktop

# PyPIパッケージのサーバーを検査
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git

# ローカル開発中のTypeScriptサーバーを検査
npx @modelcontextprotocol/inspector node path/to/server/index.js args...

# ローカル開発中のPythonサーバーを検査
npx @modelcontextprotocol/inspector uv --directory path/to/server run package-name args...

# macOSでログをリアルタイム監視
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

# macOS
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
# DevToolsを開く: Command-Option-Shift-i

# Python: MCPのログ通知を使用
server.request_context.session.send_log_message(
    level="info",
    data="Server started successfully",
)

// TypeScript: MCPのログ通知を使用
server.sendLoggingMessage({
  level: "info",
  data: "Server started successfully",
});

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\absolute\\path\\to\\my-server",
        "run",
        "server.py"
      ]
    }
  }
}

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\my-server\\build\\index.js"]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\data"
      ]
    }
  }
}

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/my-server",
        "run",
        "server.py"
      ]
    }
  }
}

# stdioトランスポートでサーバーを追加
claude mcp add my-server uv --directory /path/to/server run server.py

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["path/to/server/build/index.js"]
      }
    }
  }
}

// package.json
{
  "name": "@your-scope/mcp-server-myapp",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "mcp-server-myapp": "./build/index.js"
  },
  "files": ["build"],
  "scripts": {
    "build": "tsc && chmod 755 build/index.js"
  }
}

# ビルド & 公開
npm run build
npm publish

npx -y @your-scope/mcp-server-myapp

# pyproject.toml
[project]
name = "mcp-server-myapp"
version = "1.0.0"
dependencies = ["mcp[cli]>=1.2.0", "httpx"]

[project.scripts]
mcp-server-myapp = "mcp_server_myapp:main"

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

# ビルド & 公開
uv build
uv publish

uvx mcp-server-myapp

FROM python:3.12-slim

WORKDIR /app
COPY . .
RUN pip install -e .

ENTRYPOINT ["mcp-server-myapp"]

{
  "mcpServers": {
    "myapp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-server-myapp"]
    }
  }
}

# HTTPサーバーとして実行する場合
mcp = FastMCP("my-server")
mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)

# Python: ツール実行エラーの例
@mcp.tool()
async def fetch_data(url: str) -> str:
    """URLからデータを取得。"""
    try:
        async with httpx.AsyncClient() as client:
            response = await client.get(url, timeout=30.0)
            response.raise_for_status()
            return response.text
    except httpx.HTTPError as e:
        # エラーメッセージを文字列として返す（MCPが自動的にisError:trueに）
        return f"データ取得に失敗: {str(e)}"