ParthibanRajasekaran/mcp-weather

MCP Data Server �

A comprehensive Model Context Protocol (MCP) server that provides various data services, starting with real-time weather data and designed for easy extension to other data sources.

🚀 Features

• Modular Architecture: Easy to extend with new data services
• Real-time Weather Data: Get current weather conditions for any city
• MCP Protocol Compliance: Fully compatible with the Model Context Protocol
• TypeScript Support: Written in TypeScript for better type safety
• Stdio Transport: Uses standard input/output for communication
• Extensible Design: Ready for news, finance, sports, and other data services

📋 Prerequisites

• Node.js (v18 or higher)
• npm or yarn package manager
• TypeScript support

🛠️ Installation

1. Clone the repository:

git clone https://github.com/ParthibanRajasekaran/mcp-weather.git
cd mcp-weather

2. Install dependencies:

npm install

3. Build the project (optional):

npm run build

🎯 Usage

Running the Server

Development Mode

npm run dev

Production Mode

npm run build
npm start

MCP Configuration

Add the following configuration to your MCP client's configuration file (.vscode/mcp.json):

{
    "servers": {
        "mcp-data-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "tsx",
                "src/main.ts"
            ]
        }
    }
}

🔧 Available Services

Weather Service

getWeather

Get current weather data for a specified city.

Parameters:

• city (string): The name of the city to get weather for

Example Usage:

// MCP client call
const weather = await mcpClient.callTool("getWeather", { city: "London" });

Response Format:

{
  "latitude": 51.51147,
  "longitude": -0.13078308,
  "current": {
    "time": "2025-07-08T06:15",
    "temperature_2m": 13.9,
    "apparent_temperature": 11,
    "is_day": 1,
    "rain": 0
  },
  "hourly": {
    "time": [...],
    "temperature_2m": [...]
  }
}

🔮 Future Services (Planned)

• News Service: Get latest news from various sources
• Finance Service: Stock prices, market data, cryptocurrency
• Sports Service: Live scores, team statistics, schedules
• Social Media Service: Trending topics, social metrics
• Maps Service: Location data, directions, places

🏗️ Architecture

Project Structure

mcp-weather/
├── src/
│   ├── main.ts              # Main server entry point
│   ├── services/            # Data service implementations
│   │   └── weather.ts       # Weather service
│   ├── types/               # TypeScript type definitions
│   │   ├── weather.ts       # Weather-related types
│   │   └── service.ts       # Base service interfaces
│   └── utils/               # Utility functions
│       └── registry.ts      # Service registry
├── .vscode/
│   └── mcp.json            # MCP client configuration
├── package.json            # Project dependencies and scripts
├── tsconfig.json           # TypeScript configuration
└── README.md              # This file

Transport Layer

The server uses StdioServerTransport for communication:

• Input: Standard input (stdin)
• Output: Standard output (stdout)
• Protocol: JSON-RPC over stdio
• Benefits: Simple, reliable, and widely supported

Service Architecture

Each service follows this pattern:

// 1. Define types
interface ServiceInput { /* ... */ }
interface ServiceOutput { /* ... */ }

// 2. Create service class
class MyService {
    async getData(input: ServiceInput): Promise<string> {
        // Implementation
    }
}

// 3. Register with MCP server
server.tool("myTool", "Description", schema, handler);

🤖 AI Assistant Integration

Claude Desktop (Available Now)

Your MCP server works with Claude Desktop out of the box! See for setup instructions.

GitHub Copilot (Coming Soon)

GitHub Copilot doesn't support MCP yet, but your server is ready! See for:

• Current workarounds using VS Code extensions
• What to expect when MCP support is added
• Example integration patterns

VS Code Extension Example

Check out for a working example that integrates your MCP server with VS Code today!

🔍 MCP Inspector Integration

For debugging and development, you can use the MCP Inspector:

1. Install the MCP Inspector:

npm install -g @modelcontextprotocol/inspector

2. Run the inspector:

npx @modelcontextprotocol/inspector npx tsx src/main.ts

3. Open the inspector in your browser at http://localhost:5173

🧪 Development

Adding New Services

1. Create Type Definitions (src/types/myservice.ts):

export interface MyServiceInput {
    query: string;
}

export const MyServiceSchema = z.object({
    query: z.string().describe("Your query parameter")
});

2. Implement Service (src/services/myservice.ts):

export class MyService {
    async getData(input: MyServiceInput): Promise<string> {
        // Your implementation
        return "Service response";
    }
}

3. Register Tool (in src/main.ts):

server.tool(
    "myTool",
    "Description of my tool",
    MyServiceSchema,
    async ({ query }: { query: string }) => {
        const result = await myService.getData({ query });
        return {
            content: [{ type: "text", text: result }]
        };
    }
);

Development Scripts

• npm run dev - Run in development mode with hot reload
• npm run build - Build the TypeScript project
• npm start - Run the built project
• npm test - Run all tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage report

🌐 API Details

Weather Service API

• Geocoding: https://geocoding-api.open-meteo.com/v1/search
• Weather: https://api.open-meteo.com/v1/forecast
• Rate Limit: Free tier, no authentication required
• Model: UKMO Seamless (UK Met Office)

🤝 Contributing

We welcome contributions for new data services! Here's how:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-service
3. Add your service following the architecture above
4. Add tests and documentation
5. Commit your changes: git commit -m 'Add new service'
6. Push to the branch: git push origin feature/new-service
7. Open a Pull Request

Service Guidelines

• Each service should be self-contained in its own file
• Use TypeScript for type safety
• Include proper error handling
• Add JSDoc comments for public methods
• Follow the existing code style

📄 License

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

🙏 Acknowledgments

• Model Context Protocol for the protocol specification
• Open-Meteo for the free weather API
• TypeScript for type safety

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Contact:

🔄 Changelog

v1.0.0

• Initial release with weather service
• Modular architecture for easy extension
• MCP protocol compliance
• TypeScript implementation
• Stdio transport support

Made with ❤️ by ParthibanRajasekaran | Ready for extension to any data service! const server = new McpServer({ name: "MCP Weather Server", version: "1.0.0", description: "A server that provides weather data" });

## 🔧 Tools Available

### `getWeather`

Retrieves current weather conditions and forecasts for a specified city.

**Parameters:**
- `city` (string): The name of the city to get weather data for

**Returns:**
- Current temperature, apparent temperature, and conditions
- Hourly temperature forecast for the next 7 days
- Location coordinates and timezone information

**Example Usage:**
```typescript
// Through MCP client
const weatherData = await mcpClient.callTool("getWeather", { city: "London" });

📁 Project Structure

mcp-weather/
├── .vscode/
│   └── mcp.json              # MCP server configuration
├── weather/
│   └── main.ts               # Main server implementation
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

🔍 MCP Inspector Integration

To use with the MCP Inspector for debugging and development:

1. Configure MCP Client: Add the server to your MCP configuration file (.vscode/mcp.json):

{
    "servers": {
        "my-weather-server": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "tsx", "weather/main.ts"]
        }
    }
}

2. Launch Inspector: The server can be inspected using MCP-compatible tools and inspectors.

3. Debug Mode: Use the development server for real-time debugging:

npm run dev

🌐 API Integration

The server integrates with two Open-Meteo APIs:

Geocoding API

• Endpoint: https://geocoding-api.open-meteo.com/v1/search
• Purpose: Convert city names to coordinates
• Features: Multi-language support, fuzzy matching

Weather API

• Endpoint: https://api.open-meteo.com/v1/forecast
• Purpose: Retrieve weather data using coordinates
• Model: UK Met Office Seamless model (ukmo_seamless)
• Data: Current conditions + hourly forecasts

🛠️ Development

Available Scripts

# Development server with hot reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Start production server
npm start

# Run tests
npm test

Adding New Features

1. New Tools: Add tools to the server using the server.tool() method
2. Enhanced Data: Extend the weather API calls to include more parameters
3. Error Handling: Improve error handling for edge cases

🌍 Usage Examples

Basic Weather Query

// Get weather for London
const result = await getWeather({ city: "London" });

// Current conditions
console.log(`Temperature: ${result.current.temperature_2m}°C`);
console.log(`Feels like: ${result.current.apparent_temperature}°C`);
console.log(`Rain: ${result.current.rain}mm`);

Multi-City Comparison

const cities = ["London", "Paris", "New York", "Tokyo"];
const weatherData = await Promise.all(
    cities.map(city => getWeather({ city }))
);

🔐 Error Handling

The server includes comprehensive error handling:

• Invalid Cities: Returns helpful error messages for non-existent cities
• API Failures: Graceful handling of network issues
• Data Validation: Input validation using Zod schemas

📊 Data Schema

Current Weather Response

interface WeatherResponse {
    latitude: number;
    longitude: number;
    timezone: string;
    current: {
        time: string;
        temperature_2m: number;
        apparent_temperature: number;
        is_day: number;
        rain: number;
    };
    hourly: {
        time: string[];
        temperature_2m: number[];
    };
}

🤝 Contributing

1. Fork the repository
2. Create a 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 ISC License - see the file for details.

🙏 Acknowledgments

• Open-Meteo for providing free weather data
• Model Context Protocol for the MCP specification
• UK Met Office for the weather model data

📞 Support

For questions or issues:

• Create an issue on GitHub
• Check the MCP Documentation

Built with ❤️ using the Model Context Protocol