(Demo) MCP Server for MeteoSwiss Data
A Model Context Protocol (MCP) server for MeteoSwiss weather data.
Overview
This server provides weather data from MeteoSwiss using the Model Context Protocol (MCP), allowing AI assistants like Claude to access weather information.
Features
- Weather reports for regions in Switzerland (North, South, West)
- Search MeteoSwiss website content across multiple topics
- Fetch full content from MeteoSwiss pages with format conversion
- Multi-language support (German, French, Italian, English)
- Weather forecasts with daily breakdowns
- Intelligent HTTP caching with ETag support
- Test fixtures for development
Architecture
This MCP server runs as an HTTP service with Server-Sent Events (SSE) for real-time communication. It's designed to be accessed remotely using mcp-remote for Claude Desktop integration.
Quick Start
This server runs as an HTTP service and can be accessed using mcp-remote:
# Start the server
npm start # or: pnpm start
# In Claude Desktop, use:
npx mcp-remote http://localhost:3000/mcp
Development Mode
For development with auto-reload:
# Start with file watching
npm run dev # or: pnpm dev
# Test with MCP Inspector
npm run dev:inspect
Development
This project uses tsx for TypeScript execution, providing a smooth development experience with hot reloading.
Prerequisites
- Node.js v18.0.0 or later (we recommend using nvm for Node.js version management)
- pnpm for package management
Setting up the development environment
-
Clone the repository:
git clone https://github.com/eins78/mcp-server-meteoswiss-data.git cd mcp-server-meteoswiss-data -
Install dependencies:
pnpm install -
Use the correct Node.js version:
nvm use
Running the application
Running the Server
The server runs as an HTTP service with Server-Sent Events (SSE):
# Start the server (default port 3000)
pnpm start
# Or specify a custom port
PORT=8080 pnpm start
The HTTP server provides:
- GET
/- Server information - GET
/mcp- MCP SSE endpoint for client connections - POST
/messages?sessionId=...- Message handling endpoint - GET
/health- Health check endpoint
Development Mode
Start the development server with hot reloading:
pnpm run dev
Or run the application without hot reloading:
pnpm run start
Type checking
Check TypeScript types without emitting JavaScript files:
pnpm run lint
Project Structure
src/- Source codeindex.ts- Application entry pointdata/- Data access and transformationschemas/- Zod schemas for data validationtools/- Utility tools and scriptssupport/- Supporting infrastructure (logging, validation, etc.)
Documentation
docs/- Project documentationarchitecture/- Architecture diagrams and descriptionsanalysis/- Data analysis and insights
Available Tools
meteoswissWeatherReport
Get official MeteoSwiss weather reports for Swiss regions.
Parameters:
region: Swiss region (north,south, orwest)north: Northern Switzerland (Zurich, Basel, Bern, Swiss Plateau)south: Southern Switzerland (Ticino and southern valleys)west: Western Switzerland/Romandy (Geneva, Lausanne, western Alps)
language: Report language (de,fr, orit- English not available)- Default:
de
- Default:
Returns: Detailed weather report with daily forecasts, temperatures, and regional conditions.
search
Search MeteoSwiss website content with pagination and multi-language support.
fetch
Retrieve full content from MeteoSwiss pages in various formats (markdown, text, HTML).
See the API documentation for detailed tool specifications.
Available Prompts
Pre-configured prompts for common weather queries:
German
wetterNordschweiz: Current weather report for Northern SwitzerlandwetterSchweiz: Interactive prompt for any Swiss region
French
meteoSuisseRomande: Current weather report for Western Switzerland (Romandy)
Italian
meteoTicino: Current weather report for Southern Switzerland (Ticino)
Debugging
For issues with Claude Desktop connections or other debugging needs, see our Debugging Guide.
Running Your Own Instance
Using Node.js
# Clone the repository
git clone https://github.com/eins78/mcp-server-meteoswiss.git
cd mcp-server-meteoswiss
# Install dependencies
pnpm install
# Start the server
pnpm start
# The server will be available at http://localhost:3000
Using Docker
# Run the latest version
docker run -p 3000:3000 -e USE_TEST_FIXTURES=false meteoswiss-mcp-server
# Or build your own
docker build -t my-meteoswiss-server .
docker run -p 3000:3000 my-meteoswiss-server
# Run with custom external port mapping
# Internal port 3000 mapped to external port 8080
docker run -p 8080:3000 -e PUBLIC_URL=http://localhost:8080 my-meteoswiss-server
# Run with custom hostname
docker run -p 80:3000 -e PUBLIC_URL=http://meteoswiss.example.com my-meteoswiss-server
Environment Variables
PORT- Server port (default: 3000)PUBLIC_URL- Full public URL including protocol and port for URL generationUSE_TEST_FIXTURES- Use test data instead of live API (default: false)DEBUG_MCHMCP- Enable debug logging (default: false)BIND_ADDRESS- Interface to bind to (default: 0.0.0.0)MAX_SESSIONS- Maximum concurrent sessions (default: 100)SESSION_TIMEOUT_MS- Session timeout in milliseconds (default: 300000)
Docker Port Mapping
When running in Docker with port mapping (e.g., -p 8080:3000), use the PUBLIC_URL environment variable to ensure URLs reflect the external port:
# Server listens on port 3000 internally, but is accessible on port 8080 externally
docker run -p 8080:3000 -e PORT=3000 -e PUBLIC_URL=http://localhost:8080 my-server
# For production with a domain name
docker run -p 443:3000 -e PORT=3000 -e PUBLIC_URL=https://api.example.com my-server
Local MCP Configuration
To use your local instance with Claude Desktop, add this to your configuration:
{
"mcpServers": {
"meteoswiss-local": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:3000/mcp"]
}
}
}
Contributing
Contributions are welcome! Please ensure you follow the architecture guidelines outlined in the documentation.
License
ISC
Acknowledgments
- MeteoSwiss for providing the weather data
- Anthropic for the MCP specification