mcp-weather by JRomeoSalazar - MCP Server

MCP Weather Server

A PHP-based Model Context Protocol (MCP) server that provides weather information through the Open-Meteo API. This project demonstrates how to build an MCP server in PHP and integrate it with AI applications like Claude Code.

What is MCP?

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems. Think of it like a USB-C port for AI applications—it provides a standardized way to connect AI apps to data sources, tools, and workflows.

Features

Weather Data Retrieval: Fetch current weather and forecasts for any city
Geocoding Support: Automatically converts city names to coordinates
MCP Protocol: Built on the Model Context Protocol for seamless AI integration
Auto-Discovery: Tools are automatically discovered via PHP attributes

Prerequisites

PHP 8.0 or higher
Composer
Internet connection (for Open-Meteo API access)

Installation

Clone the repository:

git clone <repository-url>
cd mcp-weather

Install dependencies:
```
composer install
```

Usage

Running the Server

The MCP server uses stdio transport for communication:

php weather.php

VS Code Integration

The server is pre-configured for VS Code integration via .vscode/mcp.json. This allows AI assistants like Claude Code to automatically discover and use the weather tools.

Available Tools

`fetch-weather`

Fetches weather information for a specified city.

Parameters:

city (string): Name of the city (e.g., "London", "New York", "Tokyo")

Returns: JSON string containing weather data including:

Current temperature and conditions
Hourly forecasts
Weather codes and descriptions

Example:

// Called via MCP protocol
fetch-weather("Paris")

Architecture

MCP Server Configuration

The server (weather.php) is built using the MCP SDK's builder pattern:

Uses StdioTransport for communication
Auto-discovers tools in the src/ directory
Tools are registered via PHP attributes (#[McpTool])

Data Flow

City name → Open-Meteo Geocoding API → Latitude/Longitude
Coordinates → Open-Meteo Forecast API → Weather data (JSON)

Project Structure

mcp-weather/
├── src/
│   ├── Mcp/
│   │   └── Weather/
│   │       └── WeatherElements.php    # Weather tool implementation
│   └── ZodPhp/                        # Custom validation library
│       ├── Zod.php
│       ├── Schema.php
│       ├── NumberSchema.php
│       ├── StringSchema.php
│       └── BooleanSchema.php
├── weather.php                        # MCP server entry point
├── composer.json                      # Dependencies
└── CLAUDE.md                          # Claude Code instructions

Development

Creating New Tools

To add a new MCP tool:

Create a class in src/Mcp/ or a subdirectory
Add public methods with the #[McpTool] attribute:

use Mcp\Attributes\McpTool;

class MyTools {
    #[McpTool(
        name: 'my-tool',
        description: 'Description of what the tool does'
    )]
    public function myTool(string $param): string {
        // Implementation
        return "result";
    }
}

The tool will be automatically discovered when the server starts

ZodPhp Validation

The project includes a custom validation library inspired by Zod (TypeScript):

use Jorge\McpWeather\ZodPhp\Z;

// Validate numbers
$result = Z::number()->min(0)->max(100)->safe_parse($value);

// Validate strings
$result = Z::string()->min(3)->safe_parse($value);

// Validate booleans
$result = Z::boolean()->safe_parse($value);

Test the validation library:

php test-zod.php

Dependencies

mcp/sdk (dev-main) - MCP server functionality
guzzlehttp/guzzle - HTTP client for API requests

External APIs

This project uses the following free APIs:

Open-Meteo Geocoding API - Convert city names to coordinates
Open-Meteo Forecast API - Fetch weather data

License

[Your License Here]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

JRomeoSalazar/mcp-weather