weather-mcp

TypeScript MCP server that exposes weather tools backed by OpenWeatherMap.

Tools

Tool	Description
get_current_weather	Current conditions by city name or lat/lon
get_forecast	5-day / 3-hour forecast by lat/lon

Transports

Mode	Env	Use when
stdio (default)	TRANSPORT=stdio	Local Cursor / Claude Desktop
Streamable HTTP	TRANSPORT=http	Deploy (Render, etc.) / remote URL

Official MCP docs: https://modelcontextprotocol.io/docs/

Live remote (Render)

Deployed on Render’s free tier:

Base URL	https://weather-mcp-ts.onrender.com/
MCP endpoint	https://weather-mcp-ts.onrender.com/mcp
Health check	https://weather-mcp-ts.onrender.com/health

Cursor config (remote)

Add this to Settings → MCP or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "weather": {
      "url": "https://weather-mcp-ts.onrender.com/mcp"
    }
  }
}

No local build or API key in Cursor — the key lives in Render’s env vars.

Render free tier: the service shuts down after ~15 minutes of inactivity. The next request is a cold start and can take up to ~50 seconds before MCP responds. Hit /health once if Cursor tools look stuck waking up.

Prerequisites (local only)

• Node.js 20+
• pnpm (or npm/yarn)
• An OpenWeatherMap API key (get one here)

Setup (local)

pnpm install
cp .env.example .env

Edit .env and set your key:

OPEN_WEATHER_MAP_API_KEY=your_key_here
TRANSPORT=stdio

Build the server:

pnpm run build

This writes the runnable entrypoint to dist/index.js.

Add to Cursor (local stdio)

Cursor does not start this process from the project root by default for env loading, so pass the env file with an absolute path via Node’s --env-file flag.

1. Open Cursor Settings → MCP, or edit ~/.cursor/mcp.json.
2. Add a weather entry under mcpServers:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": [
        "--env-file",
        "/ABSOLUTE/PATH/TO/weather-mcp/.env",
        "/ABSOLUTE/PATH/TO/weather-mcp/dist/index.js"
      ]
    }
  }
}

Replace /ABSOLUTE/PATH/TO/weather-mcp with your real project path (e.g. run pwd from the repo root). Keep TRANSPORT=stdio (or unset) in .env.

Alternative: env inline

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/weather-mcp/dist/index.js"
      ],
      "env": {
        "OPEN_WEATHER_MAP_API_KEY": "your_key_here",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Prefer .env + --env-file so the key stays out of mcp.json.

1. Save, then toggle the server off/on in Settings → MCP (or restart Cursor).
2. Confirm the server shows as connected and lists get_current_weather and get_forecast.

After code changes

pnpm run build

Then reload the MCP server in Cursor.

Streamable HTTP (local)

HTTP mode serves MCP at POST/GET /mcp (configurable) plus GET /health. Streamable HTTP is configured via the official SDK’s createMcpHandler + toNodeHandler.

pnpm run build
TRANSPORT=http PORT=3000 pnpm run start
# or
pnpm run start:http

You should see something like:

Weather MCP Server running on http://0.0.0.0:3000/mcp (Streamable HTTP)

Deploy on Render

1. Create a Web Service from this repo (root of the project).
2. Build: pnpm install && pnpm run build (or npm equivalent).
3. Start: node dist/index.js (or pnpm run start).
4. Env vars:
   • TRANSPORT=http
   • OPEN_WEATHER_MAP_API_KEY=...
   • PORT is set by Render automatically
5. MCP URL: https://<your-service>.onrender.com/mcp
   This deployment: https://weather-mcp-ts.onrender.com/mcp

The HTTP endpoint is unauthenticated. Anyone with the URL can call the tools. Add auth before sharing widely.

Manual smoke check (OpenWeatherMap)

With .env set:

node --env-file=.env -e "
import { getApiKey, buildCurrentWeatherUrl, makeOWMRequest, formatCurrentWeather } from './dist/utils.js';
const apiKey = getApiKey();
const data = await makeOWMRequest(buildCurrentWeatherUrl({ apiKey, city: 'Yaounde,CM', units: 'metric' }));
console.log(data ? formatCurrentWeather(data, 'metric') : 'failed');
"

Remote health:

curl -s https://weather-mcp-ts.onrender.com/health

Repo layout

weather-mcp/
├── README.md
├── package.json
├── tsconfig.json
├── .env.example
└── src/
    ├── index.ts      # stdio + Streamable HTTP entry
    ├── server.ts     # tool registration
    ├── types.ts
    └── utils.ts

Notes

• Never commit .env (it is gitignored).
• Stdio servers must not write to stdout except MCP JSON-RPC; logs go to stderr (console.error).
• Free OpenWeatherMap plans cover current weather and the 5-day / 3-hour forecast used here.

License

ISC