brightsky-mcp-server by unravellingtechnologies - MCP Server

Bright Sky MCP Server

A Model Context Protocol (MCP) server that provides secure, standardized access to German weather data from the Deutscher Wetterdienst (DWD) through the Bright Sky API. This server enables seamless integration with MCP-compatible tools like Claude Desktop.

🚀 Quick Start

# Install and run with npx (recommended)
npx @unravellingtechnologies/brightsky-mcp-server

# Or install globally
npm install -g @unravellingtechnologies/brightsky-mcp-server
brightsky-mcp-server

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
	"mcpServers": {
		"brightsky": {
			"command": "npx",
			"args": ["@unravellingtechnologies/brightsky-mcp-server"]
		}
	}
}

📋 Features

🌤️ Current Weather: Get real-time weather conditions for any German location
📅 Weather Forecasts: Access multi-day weather predictions using MOSMIX model
📊 Historical Data: Retrieve past weather information for analysis
📍 Weather Stations: Find nearby weather monitoring stations
🔐 No Authentication: Uses the publicly accessible Bright Sky API
🔌 MCP Compatible: Works with any MCP-compatible client
⚡ High Performance: <200ms average response time
🛡️ Secure: Comprehensive input validation and rate limiting
📦 Easy Installation: Single-command setup via npx

🏗️ Architecture

This MCP server is built with a focus on reliability and minimal dependencies:

Native Node.js Features: Uses built-in fetch, crypto, and other APIs
JavaScript: Clean, maintainable code with modern ES modules
MCP Protocol: Full compliance with Model Context Protocol specification
Minimal Dependencies: Only essential MCP SDK dependency
Cross-Platform: Works on Windows, macOS, and Linux

🎨 Code Quality

This project maintains high code quality standards:

ESLint: Configured with recommended rules for JavaScript
Prettier: Consistent code formatting across the project
Pre-commit Hooks: Automated formatting and linting checks
Comprehensive Testing: Unit and integration tests for all functionality
Type Safety: JSDoc annotations for better IDE support

🛠️ Installation

Prerequisites

Node.js >=20.0.0 (LTS recommended)
npm or yarn package manager

Quick Installation

# Run directly with npx (recommended)
npx @unravellingtechnologies/brightsky-mcp-server

# Or install globally
npm install -g @unravellingtechnologies/brightsky-mcp-server

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
	"mcpServers": {
		"brightsky": {
			"command": "npx",
			"args": ["@unravellingtechnologies/brightsky-mcp-server"]
		}
	}
}

📖 Documentation

Setup Guides

- Complete guide for integrating with Claude Desktop
- Comprehensive compatibility guide for all MCP clients
- Common issues and solutions
- Code examples for various client types

Configuration Files

claude_desktop_config.json.example - Sample Claude Desktop configuration
tests/mcp-client-test.js - Basic MCP client test script
tests/mcp-compatibility-test.js - Comprehensive compatibility test suite

📚 API Reference

Core Weather Operations

`get_current_weather`

Get current weather conditions for a specific location.

Parameters:

latitude (number): Latitude coordinate (-90 to 90)
longitude (number): Longitude coordinate (-180 to 180)
date (string, optional): Date in YYYY-MM-DD format (defaults to current date)

Returns:

Current weather data including temperature, humidity, pressure, wind speed, and conditions

`get_weather_forecast`

Get weather forecast for upcoming days.

Parameters:

latitude (number): Latitude coordinate
longitude (number): Longitude coordinate
days (number): Number of forecast days (1-10)

Returns:

Multi-day weather forecast with hourly and daily breakdowns

`get_historical_weather`

Get historical weather data for analysis.

Parameters:

latitude (number): Latitude coordinate
longitude (number): Longitude coordinate
start_date (string): Start date in YYYY-MM-DD format
end_date (string): End date in YYYY-MM-DD format

Returns:

Historical weather observations for the specified date range

`search_weather_stations`

Find nearby weather stations.

Parameters:

latitude (number): Latitude coordinate
longitude (number): Longitude coordinate
radius (number, optional): Search radius in kilometers (defaults to 50km)

Returns:

List of nearby weather stations with metadata and distance information

💡 Usage Examples

Get Current Weather for Berlin

// In your MCP client
const weather = await mcpClient.callTool('get_current_weather', {
	latitude: 52.52,
	longitude: 13.405,
})

console.log(weather)
// Output: { temperature: 15.2, humidity: 65, pressure: 1013.2, ... }

Get 5-Day Forecast for Munich

const forecast = await mcpClient.callTool('get_weather_forecast', {
	latitude: 48.1351,
	longitude: 11.582,
	days: 5,
})

console.log(forecast.days)
// Output: Array of 5 forecast days with detailed weather data

Find Weather Stations Near Hamburg

const stations = await mcpClient.callTool('search_weather_stations', {
	latitude: 53.5511,
	longitude: 9.9937,
	radius: 25,
})

console.log(stations)
// Output: Array of nearby weather stations with distances

Get Historical Weather Data

const historical = await mcpClient.callTool('get_historical_weather', {
	latitude: 50.1109,
	longitude: 8.6821,
	start_date: '2024-01-01',
	end_date: '2024-01-31',
})

console.log(historical)
// Output: Historical weather data for January 2024

🌍 Data Sources

This server uses data from the Bright Sky API, which provides access to weather data from the German Weather Service (Deutscher Wetterdienst - DWD). The data includes:

Real-time Observations: Current weather data from DWD weather stations
Weather Forecasts: Predictions using the MOSMIX model
Historical Data: Past weather observations for analysis and research
Station Information: Metadata about weather monitoring stations

🔧 Technical Details

Technology Stack

Runtime: Node.js 20+ (LTS)
Language: TypeScript
Protocol: Model Context Protocol (MCP)
HTTP Client: Native fetch API
Validation: Custom JSON schema validation
Testing: Node.js built-in test runner
Deployment: npx-compatible package

Performance Targets

Response Time: <200ms average
Concurrent Requests: 100+ supported
Memory Usage: <50MB footprint
Uptime: 99.9% availability target

Security Features

Input Validation: Comprehensive validation for all parameters
Rate Limiting: 100 requests per minute per client
Coordinate Bounds: Validation for German territory
Error Handling: Secure error responses without information leakage
No Data Storage: Server does not store any user data

🚦 Development Status

✅ Completed

📋 Planned

npm package publication
Community feedback and improvements

🤝 Contributing

We welcome contributions! Please see our for details.

Development Setup

# Clone the repository
git clone https://github.com/unravellingtechnologies/brightsky-mcp-server.git
cd brightsky-mcp-server

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Run integration tests
npm run test:integration

# Run MCP client compatibility tests
npm run test:mcp-client
npm run test:mcp-compatibility

# Run all tests
npm run test:all

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code with Prettier
npm run format

# Check code formatting
npm run format:check

# Format only source files
npm run format:src

# Clean build artifacts
npm run clean

📄 License

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

🆘 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation:

📈 Roadmap

v1.0.0 (Q1 2025)

Core weather operations
MCP protocol compliance
Claude Desktop integration
npx installation support

v1.1.0 (Q2 2025)

Caching improvements
Performance optimizations
Additional weather data sources
Enhanced error handling

v2.0.0 (Q3 2025)

Multi-API support
Advanced analytics
Mobile optimization
Enterprise features

🙏 Acknowledgments

This project is built on top of the excellent work of the open-source community:

Bright Sky - The open-source JSON API that provides free access to German weather data from the DWD. This MCP server would not be possible without their excellent work.
- Website: brightsky.dev
- GitHub Repository: github.com/jdemaeyer/brightsky
Deutscher Wetterdienst (DWD) - Germany's national meteorological service for providing the underlying weather data
Model Context Protocol - For the standardized interface that enables seamless integration with AI tools
Anthropic - For Claude Desktop and the MCP ecosystem

Made with ❤️ for the German weather data community