Skip to main content
Glama
Sousam2002

Weather & Location MCP Server

by Sousam2002
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

Weather & Location MCP Server

A beginner-friendly MCP server built with TypeScript, Node.js, the MCP TypeScript SDK, OpenWeather API, dotenv, and zod.

Features

  • getCurrentWeather(city)

  • getForecast(city)

  • getAirQuality(city)

  • Sunrise and sunset information

  • Environment variable support with dotenv

  • Input validation with zod

  • TypeScript response types for API data

  • Helpful error handling

Related MCP server: Weather MCP Server

Tech Stack

  • TypeScript

  • Node.js

  • @modelcontextprotocol/sdk

  • OpenWeather API

  • dotenv

  • zod

Project Structure

weather-location-mcp-server/
|- src/
|  |- index.ts
|  |- weatherApi.ts
|  `- types.ts
|- .env.example
|- .gitignore
|- package.json
|- README.md
`- tsconfig.json

Setup

1. Install dependencies

npm install

2. Create your environment file

Create a .env file in the project root:

OPENWEATHER_API_KEY=your_api_key_here

You can copy from .env.example and replace the placeholder value with your real OpenWeather API key.

3. Build the project

npm run build

Run the Server

Development mode

npm run dev

Production build

npm run build
npm run start

The server runs over stdio, so it will wait quietly for an MCP client to connect.

Available Tools

getCurrentWeather

Input:

{
  "city": "Delhi"
}

Returns:

  • City name

  • Country

  • Weather condition and description

  • Temperature

  • Feels-like temperature

  • Humidity

  • Sunrise time

  • Sunset time

getForecast

Input:

{
  "city": "Delhi"
}

Returns:

  • City name

  • Country

  • First 5 forecast entries

  • Temperature

  • Weather condition and description

getAirQuality

Input:

{
  "city": "Delhi"
}

Returns:

  • AQI value

  • AQI label

  • CO

  • NO2

  • O3

  • PM2.5

  • PM10

Using with Codex

If you want Codex to use this server as an MCP tool provider, add a project config file at .codex/config.toml:

[mcp_servers.weather_location]
command = "node"
args = ["dist/index.js"]
cwd = "D:\\My PC\\Coding\\web development\\Weather & Location MCP Server"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60

Then restart Codex or open a new thread in the project.

Notes

  • Keep .env out of GitHub because it contains your API key.

  • Keep .codex/ out of GitHub if it contains your personal local Codex setup.

  • This project uses Node.js native fetch.

License

ISC

Available Tools

3 tools
getAirQualityGet Air QualityB

Get air quality information for a city

ParametersJSON Schema
NameRequiredDescriptionDefault
cityYesThe city name

TDQS

B3/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It provides no information about side effects, constraints, rate limits, or what data is returned (e.g., AQI, pollutants). The tool is essentially a black box beyond its name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no extraneous words. It is appropriately sized for a simple tool and front-loads the key action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema, the description should hint at what information is returned (e.g., air quality index, specific pollutants). It does not, leaving the agent uncertain about the tool's output beyond 'air quality information'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (one parameter 'city' with description 'The city name'). The description adds no additional meaning beyond what the schema provides, so it meets the baseline but does not enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get air quality information for a city' clearly states the action (get) and resource (air quality information) with context (city). It distinguishes from sibling tools like getCurrentWeather and getForecast, which focus on weather rather than air quality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool vs. siblings. The description does not mention alternatives like getCurrentWeather for weather data or specify any prerequisites or context for when air quality should be retrieved.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getCurrentWeatherGet Current WeatherC

Get the current weather for a city

ParametersJSON Schema
NameRequiredDescriptionDefault
cityYesThe city name

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, and the description omits behavioral traits such as data freshness, rate limits, or whether the result is real-time vs cached. For a simple read tool, this is insufficiently transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that efficiently conveys the core purpose with no extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and no output schema, but the description does not specify what data is returned (e.g., temperature, conditions). This leaves the agent guessing about the output format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of parameters, and the description does not add meaning beyond what the schema provides (city name). Baseline of 3 is appropriate since schema already defines the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and resource ('current weather') with a city scope. It distinguishes from siblings (getAirQuality, getForecast) by focusing on current weather, though it does not explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., getForecast for future data, getAirQuality for pollutants). The agent must infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getForecastGet ForecastC

Get a weather forecast for a city

ParametersJSON Schema
NameRequiredDescriptionDefault
cityYesThe city name

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, and the description provides no behavioral context such as read-only nature, required permissions, or output format. For a forecast tool, details like time range or data units would be helpful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no extraneous words. It efficiently conveys the basic purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 parameter, no output schema), the description is too minimal. It lacks information about what the forecast includes (e.g., temperature, precipitation) and how it differs from getCurrentWeather.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the 'city' parameter description 'The city name' is adequate. The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get a weather forecast for a city', which matches the tool name and indicates a specific resource. However, it does not distinguish from sibling tools like getCurrentWeather, which could also involve weather data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus its siblings (getAirQuality, getCurrentWeather). The agent is left to infer the difference from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedgetAirQuality
    • First observedgetCurrentWeather
    • First observedgetForecast
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Scored across 3 tools

Disambiguation5/5

Each tool returns a distinct type of weather information (air quality, current weather, forecast), so an agent can easily select the correct one without ambiguity.

Naming Consistency5/5

All tool names follow a consistent 'get' + noun pattern in camelCase (getAirQuality, getCurrentWeather, getForecast), making them predictable and easy to remember.

Tool Count5/5

Three tools is a well-scoped set for a weather service, covering the most common queries without being overly sparse or bloated.

Completeness4/5

The set covers the essential weather operations (current, forecast, air quality). One could argue for additional tools like weather alerts or historical data, but the core is complete.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers