🌤️ MCP Weather Server

A simple Model Context Protocol (MCP) Weather Server built with Node.js that exposes weather functionality as an MCP tool.

This project demonstrates how an MCP server can expose tools that an AI application or MCP client can discover and execute.

🚀 Built as a practical project to understand MCP Servers, MCP Tools, stdio transport, Zod validation, and external API integration.

✨ Features

• 🔌 MCP server using the official MCP SDK

• 🛠️ Custom MCP tool: getWeatherDataByCityName

• 📍 Weather lookup by city name

• 🔐 Environment-variable based API configuration

• ✅ Input validation using Zod

• 📡 MCP communication using StdioServerTransport

• ⚡ Built with Node.js and JavaScript

• 🧪 Testable with MCP Inspector

• 🤖 Compatible with MCP clients that support stdio transport

Related MCP server: weather-mcp-server

🏗️ Architecture

                ┌─────────────────────┐
                │     MCP Client      │
                │                     │
                │ Cursor / Inspector  │
                │ Other MCP Client    │
                └──────────┬──────────┘
                           │
                           │ MCP / stdio
                           ▼
                ┌─────────────────────┐
                │    MCP Weather      │
                │       Server        │
                │      index.js       │
                └──────────┬──────────┘
                           │
                           ▼
              ┌─────────────────────────┐
              │ getWeatherDataByCityName│
              └────────────┬────────────┘
                           │
                           ▼
                ┌─────────────────────┐
                │   Weather Service   │
                │    External API     │
                └─────────────────────┘

🧰 Tech Stack

📂 Project Structure

MyMcp/
│
├── index.js
├── package.json
├── pnpm-lock.yaml
├── .env
├── .env.example
├── .gitignore
└── README.md

📦 Installation

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/mcp-weather-server.git

cd mcp-weather-server

2. Install dependencies

This project uses pnpm.

pnpm install

🔐 Environment Variables

Create a .env file:

WEATHER_API_KEY=your_weather_api_key

⚠️ Never commit your .env file or API key to GitHub.

The repository should contain .env.example instead:

WEATHER_API_KEY=your_weather_api_key_here

▶️ Run the MCP Server

Start the server with:

node index.js

For an MCP stdio server, no web page or server URL is expected to appear in the terminal.

The process waits for an MCP client to communicate with it through stdin/stdout.

🧪 Test With MCP Inspector

You can test the MCP server without Cursor Agent.

Run:

pnpm dlx @modelcontextprotocol/inspector node index.js

The MCP Inspector will provide a local URL.

Open it in your browser.

You should see the available MCP tool:

getWeatherDataByCityName

Tool Input

{
  "city": "Delhi"
}

The MCP server then calls the weather service and returns weather information.

🛠️ Available MCP Tool

getWeatherDataByCityName

Gets weather information for a specified city.

Input

{
  "city": "Delhi"
}

Example Response

{
  "temp": "30°C",
  "forecast": "Clear"
}

🔄 How MCP Works in This Project

The request flow is:

User
 ↓
AI / MCP Client
 ↓
MCP Tool Call
 ↓
getWeatherDataByCityName
 ↓
Weather API
 ↓
Weather Data
 ↓
MCP Server
 ↓
MCP Client
 ↓
AI Response

The important concept is that the AI does not directly contain the weather functionality.

Instead, the AI can discover and call an MCP tool exposed by the server.

🧠 What I Learned

This project helped me understand:

• What MCP is

• Why MCP servers are useful

• MCP server architecture

• MCP tools

• Tool schemas

• Zod validation

• StdioServerTransport

• MCP client/server communication

• External API integration

• API key management

• Environment variables

• MCP Inspector

• Testing MCP tools without relying on a paid AI agent

🔒 Security

Never expose API keys in source code.

❌ Don't do:

const API_KEY = "my-secret-key";

✅ Use environment variables:

const API_KEY = process.env.WEATHER_API_KEY;

And add .env to .gitignore:

.env
node_modules/

📚 MCP Concepts Demonstrated

MCP
│
├── MCP Server
│
├── MCP Client
│
├── Tools
│
├── Tool Schema
│
├── Transport
│   └── stdio
│
└── External APIs