🌤️ FastMCP Weather Server

🌤️ FastMCP Weather Server

FastMCP と TypeScript で構築された、本番環境対応の天気 MCP サーバーです。Claude Desktop、VS Code、Cursor とシームレスに連携します。

✨ 機能

• 🌍 リアルタイムの天気データ - 世界中のあらゆる都市の現在の天気を取得できます
• 🔒 型安全 - TypeScript と Zod による検証で構築されています
• 📊 進捗レポート - 天気のリクエストに対応した進捗追跡機能を内蔵しています
• 📝 構造化ログ - コンテキストを含む包括的なログ記録
• 🛠️ 簡単なテスト - 開発とデバッグ用の CLI ツールを内蔵しています
• 🔌 幅広い連携 - Claude Desktop、VS Code、Cursor で動作します
• ⚡ 高速な開発 - 従来の MCP SDK より 5 倍高速です

🚀 クイックスタート

前提条件

• Node.js 20.18.1 以上（必須要件）
• OpenWeatherMap API キー（無料枠：1 日あたり 1,000 回の呼び出し）

インストール

git clone https://github.com/abhilashsahoo/fastmcp-weather-server.git
cd fastmcp-weather-server
npm install

セットアップ

1. OpenWeatherMap API キーを取得します：

   • openweathermap.org/api で登録します
   • ダッシュボードから API キーをコピーします

2. 環境ファイルを作成します：

   cp .env.example .env
   

3. API キーを .env に追加します：

   OPENWEATHER_API_KEY=your_api_key_here
   

開発

サーバーをテストします：

npm run dev

対話型 CLI を試します：

get_weather {"city": "London"}

ビジュアルインターフェースでデバッグします：

npm run inspect

本番環境向けにビルドします：

npm run build

🔧 MCP クライアントとの連携

Claude Desktop

1. 設定ファイルを確認します：

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows： %APPDATA%\Claude\claude_desktop_config.json

2. 次の設定を追加します：

   {
     "mcpServers": {
       "weather": {
         "command": "npx",
         "args": ["tsx", "/absolute/path/to/fastmcp-weather-server/src/server.ts"],
         "env": {
           "OPENWEATHER_API_KEY": "your_actual_api_key_here"
         }
       }
     }
   }
   

3. Claude Desktop を再起動してテストします：

   What's the weather like in Tokyo?
   

VS Code

1. MCP 拡張機能をインストールします
2. .vscode/settings.json を作成します：

   {
     "mcp.servers": {
       "weather": {
         "command": "npx",
         "args": ["tsx", "./src/server.ts"],
         "cwd": "${workspaceFolder}",
         "env": {
           "OPENWEATHER_API_KEY": "your_actual_api_key_here"
         }
       }
     }
   }
   

Cursor IDE

1. .cursor/mcp.json を作成します：

   {
     "servers": {
       "weather": {
         "command": "npx",
         "args": ["tsx", "./src/server.ts"],
         "env": {
           "OPENWEATHER_API_KEY": "your_actual_api_key_here"
         }
       }
     }
   }
   

📋 利用可能なスクリプト

スクリプト	説明
npm run dev	CLI を使用して FastMCP 開発サーバーを起動します
npm run inspect	ビジュアルデバッグインターフェースを開きます
npm run test-direct	CLI を使わずにサーバーを直接テストします
npm run build	TypeScript を JavaScript にコンパイルします
npm start	コンパイル済みサーバーを実行します

🛠️ API リファレンス

ツール

get_weather

世界中のあらゆる都市の現在の天気情報を取得します。

パラメーター：

• city（文字列、必須）：都市名（例：「London」、「New York」）

戻り値：

• 気温、天候、湿度、風速を含む、フォーマット済みの天気データ

例：

{
  "city": "London"
}

レスポンス：

🌤️ Weather in London:
🌡️ Temperature: 15°C (feels like 13°C)
☁️ Conditions: partly cloudy
💧 Humidity: 65%
💨 Wind Speed: 3.2 m/s

🐛 トラブルシューティング

よくある問題

問題	解決策
Node.js のバージョンエラー	Node.js 20.18.1 以上に更新します：winget upgrade OpenJS.NodeJS
サーバーが見つからない	MCP クライアントの設定で絶対パスを確認します
API キーのエラー	.env と MCP クライアントの環境変数セクションにある API キーを確認します
モジュール解決エラー	node_modules を削除して npm install を実行します
FastMCP CLI の問題	CLI を使わずにテストするには、npm run test-direct を試します

Windows 固有の手順

PowerShell で Node.js を更新します：

# Using Chocolatey
choco upgrade nodejs

# Using Winget
winget upgrade OpenJS.NodeJS

# Using nvm-windows
nvm install 20.18.1 && nvm use 20.18.1

テスト手順

1. サーバーを直接テストします： npm run test-direct
2. FastMCP CLI でテストします： npm run dev
3. ビジュアルインターフェースでテストします： npm run inspect
4. Claude Desktop でテストします： Claude を再起動し、天気について質問します

📊 プロジェクト構成

fastmcp-weather-server/
├── src/
│   └── server.ts          # Main FastMCP server
├── dist/                  # Compiled JavaScript (generated)
├── .env                   # Environment variables (create from .env.example)
├── .env.example           # Environment template
├── .gitignore            # Git ignore rules
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md             # This file

🌟 機能の詳細

FastMCP の利点

• 設定不要： 1 つのコンストラクターでサーバーをセットアップできます
• テスト機能を内蔵： CLI とウェブインターフェースを利用できます
• 進捗レポート： リアルタイムの進捗を更新します
• 構造化ログ： データオブジェクトを含むコンテキスト付きのログ記録
• 型安全性： Zod スキーマによる検証
• エラー処理： ユーザーにわかりやすいエラーメッセージ

天気データ

• リアルタイム更新： OpenWeatherMap から現在の気象状況を取得します
• 世界中をカバー： 世界中のあらゆる都市の天気を取得できます
• 包括的なデータ： 気温、湿度、風、天候
• レート制限： 1 日あたり 1,000 回まで無料でリクエストできます

🚀 デプロイ

開発

npm run dev  # Test with FastMCP CLI

本番環境

npm run build  # Compile TypeScript
npm start      # Run compiled server

環境変数

変数	説明	必須
OPENWEATHER_API_KEY	OpenWeatherMap API キー	はい
NODE_ENV	環境（development/production）	いいえ

📈 パフォーマンス

• リクエスト数： 1 日あたり 1,000 件の天気情報呼び出し（無料プラン）
• 応答時間： 平均 < 500ms
• メモリ使用量： < 50MB
• クライアント対応： Claude Desktop、VS Code、Cursor

🤝 貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/amazing-feature
3. 変更をコミットします：git commit -m 'Add amazing feature'
4. ブランチにプッシュします：git push origin feature/amazing-feature
5. プルリクエストを作成します

📝 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

🙏 謝辞

• FastMCP - 素晴らしい MCP フレームワーク
• OpenWeatherMap - 無料の天気情報 API
• Model Context Protocol - MCP の仕様

🔗 関連プロジェクト

• FastMCP - TypeScript の MCP フレームワーク
• FastMCP Boilerplate - スターターテンプレート
• MCP Servers - 公式 MCP サーバー

---

FastMCP と TypeScript を使用して ❤️ を込めて構築