abhilashsahoo/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

🛠️ 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

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

📈 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 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