🌤️ FastMCP Weather Server

🌤️ FastMCP Weather Server

A production-ready weather MCP server built with FastMCP and TypeScript that integrates seamlessly with Claude Desktop, VS Code, and Cursor.

✨ Features

• 🌍 Real-time Weather Data - Get current weather for any city worldwide
• 🔒 Type-Safe - Built with TypeScript and Zod validation
• 📊 Progress Reporting - Built-in progress tracking for weather requests
• 📝 Structured Logging - Comprehensive logging with context
• 🛠️ Easy Testing - Built-in CLI tools for development and debugging
• 🔌 Universal Integration - Works with Claude Desktop, VS Code, and Cursor
• ⚡ Fast Development - 5x faster than traditional MCP SDK

🚀 Quick Start

Prerequisites

• Node.js 20.18.1 or higher (critical requirement)
• OpenWeatherMap API key (free tier: 1,000 calls/day)

Installation

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

Setup

1. Get your OpenWeatherMap API key:

   • Sign up at openweathermap.org/api
   • Copy your API key from the dashboard

2. Create environment file:

   cp .env.example .env
   

3. Add your API key to .env:

   OPENWEATHER_API_KEY=your_api_key_here
   

Development

Test your server:

npm run dev

Try the interactive CLI:

get_weather {"city": "London"}

Debug with visual interface:

npm run inspect

Build for production:

npm run build

🔧 MCP Client Integration

Claude Desktop

1. Find your config file:

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

2. Add this configuration:

   {
     "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. Restart Claude Desktop and test:

   What's the weather like in Tokyo?
   

VS Code

1. Install the MCP extension
2. Create .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. Create .cursor/mcp.json:

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

📋 Available Scripts

Script	Description
npm run dev	Start FastMCP development server with CLI
npm run inspect	Open visual debugging interface
npm run test-direct	Test server directly without CLI
npm run build	Compile TypeScript to JavaScript
npm start	Run compiled server

🛠️ API Reference

Tools

get_weather

Get current weather information for any city worldwide.

Parameters:

• city (string, required): City name (e.g., "London", "New York")

Returns:

• Formatted weather data with temperature, conditions, humidity, and wind speed

Example:

{
  "city": "London"
}

Response:

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

🐛 Troubleshooting

Common Issues

Issue	Solution
Node.js version error	Update to Node.js 20.18.1+: winget upgrade OpenJS.NodeJS
Server not found	Check absolute path in MCP client configuration
API key errors	Verify API key in .env and MCP client env section
Module resolution errors	Delete node_modules and run npm install
FastMCP CLI issues	Try npm run test-direct to test without CLI

Windows-Specific

Update Node.js via PowerShell:

# Using Chocolatey
choco upgrade nodejs

# Using Winget
winget upgrade OpenJS.NodeJS

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

Testing Steps

1. Test server directly: npm run test-direct
2. Test with FastMCP CLI: npm run dev
3. Test with visual interface: npm run inspect
4. Test with Claude Desktop: Restart Claude and ask about weather

📊 Project Structure

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

🌟 Features in Detail

FastMCP Advantages

• Zero Configuration: Server setup with single constructor
• Built-in Testing: CLI and web interface included
• Progress Reporting: Real-time progress updates
• Structured Logging: Contextual logging with data objects
• Type Safety: Zod schema validation
• Error Handling: User-friendly error messages

Weather Data

• Real-time Updates: Current conditions from OpenWeatherMap
• Global Coverage: Weather for any city worldwide
• Comprehensive Data: Temperature, humidity, wind, conditions
• Rate Limiting: 1,000 free requests per day

🚀 Deployment

Development

npm run dev  # Test with FastMCP CLI

Production

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

Environment Variables

Variable	Description	Required
OPENWEATHER_API_KEY	OpenWeatherMap API key	Yes
NODE_ENV	Environment (development/production)	No

📈 Performance

• Requests: 1,000 weather calls/day (free tier)
• Response Time: < 500ms average
• Memory Usage: < 50MB
• Client Support: Claude Desktop, VS Code, Cursor

🤝 Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastMCP - The amazing MCP framework
• OpenWeatherMap - Free weather API
• Model Context Protocol - The MCP specification

🔗 Related Projects

• FastMCP - TypeScript MCP framework
• FastMCP Boilerplate - Starter template
• MCP Servers - Official MCP servers

---

Built with ❤️ using FastMCP and TypeScript