Weather MCP Server
tomripp/mcp-server
MCP server de clima com duplo transporte HTTP (JSON/SSE)
Ver no GitHubServidor MCP que fornece dados meteorológicos via API Open-Meteo, com suporte a dois modos de transporte (JSON e SSE). Implementa ferramentas para busca de localidades, clima atual, previsão e alertas severos, com endpoints HTTP estateful spec-compliant.
Instalação
npx convez-ai tomripp/mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar dados meteorológicos em agents Claude
- Testar diferentes modos de transporte MCP (JSON vs SSE)
- Fornecer contexto climático em automações e fluxos
Veredito

Exemplo técnico bem-estruturado de MCP server com implementação dual de transporte. Útil como referência ou base para integração de dados meteorológicos, mas escopo limitado a um caso de uso específico.
README
A tradução para o português deste README ainda está na fila.
Weather MCP Server
A small example Model Context Protocol server exposing weather tools, a resource template, and a prompt. It is deployed with two Streamable HTTP endpoints serving the identical capability set — one returning plain JSON, the other returning SSE — so MCP clients can be tested against both transport response modes.
Data source: Open-Meteo (free, no API key).
1. Endpoints
| Purpose | URL | Response format |
|---|---|---|
| JSON mode | https://mcpserver-production-dd31.up.railway.app/json/mcp | application/json |
| SSE mode | https://mcpserver-production-dd31.up.railway.app/sse/mcp | text/event-stream |
| Health | https://mcpserver-production-dd31.up.railway.app/health | application/json ({"status":"ok"}) |
Both MCP endpoints implement the full stateful Streamable HTTP flow:
initialize → notifications/initialized → any number of tool/resource/prompt
calls, all carrying an mcp-session-id header returned by initialize.
Both are spec-compliant — MCP's Streamable HTTP transport explicitly allows either JSON or SSE for request/response pairs. The JSON endpoint is easier to consume from generic HTTP clients (Node-RED, curl, n8n HTTP nodes); the SSE endpoint is the default behavior you'll see from most MCP SDKs.
Project files
MCPserver/
├── server.py # Dual-endpoint Starlette app + FastMCP instances
├── weather_client.py # Async Open-Meteo wrapper
├── requirements.txt # mcp[cli], httpx, starlette, uvicorn
├── Procfile
├── railway.json
├── .gitignore
└── README.md # (this file)
2. Server settings — JSON vs SSE
The server in server.py mounts the same tools/resources/prompts twice by
building two FastMCP instances with different response modes, then mounting
them under different path prefixes in a Starlette app.
Key per-instance options:
FastMCP(
name="weather-example-json",
json_response=True, # plain JSON response bodies
...
)
FastMCP(
name="weather-example-sse",
json_response=False, # default — SSE streaming
...
)
| Option | Effect |
|---|---|
json_response=True | Each response body is a single application/json blob. Easier for plain HTTP tooling. |
json_response=False (default) | Responses are served as text/event-stream frames: event: message\ndata: <json>\n\n. Matches what MCP SDKs emit by default. |
stateless_http=True | (Not used here.) Skips the session/init handshake; every request is independent. |
| Default (stateful) | Requires initialize → notifications/initialized → tool calls, with mcp-session-id header on every call after init. |
Required request headers (both endpoints)
| Header | Value |
|---|---|
Content-Type | application/json |
Accept | application/json, text/event-stream (both required by the spec) |
mcp-session-id | The session id returned in the initialize response header — set on every call after initialize. |
3. Tools, resource, and prompt
Tools
| Name | Args | Purpose |
|---|---|---|
search_locations | query: string | Geocode a place name → up to 5 candidate lat/lon results. |
get_current_weather | location: string | Current temp, humidity, wind, WMO weather code. |
get_forecast | location: string, days: int = 3 | Daily forecast (tmin/tmax, precip, code). days clamped to 1..16. |
get_severe_alerts | location: string | Synthesized severe-weather signal (heavy rain ≥25 mm, heat ≥38 °C, cold ≤ −15 °C) over the next 2 days. |
Resource (template)
| URI template | Returns |
|---|---|
weather://briefing/{location} | Bundled JSON {current, forecast (3 days), alerts} for the given location. |
Listed via resources/templates/list, read via resources/read with a concrete
URI like weather://briefing/Karlsruhe, Germany.
Prompt
| Name | Args | What it does |
|---|---|---|
weather_briefing | location: string, audience: string = "general" | Generates a user-message asking the model to use the weather tools and compose a briefing tailored to the audience. |
4. MCP Streamable HTTP flow at a glance
Client Server
│ │
│── POST /…/mcp initialize ─────────────▶│ (no session id yet)
│◀── 200 + header: mcp-session-id: <ID> ─│
│ │
│── POST /…/mcp notifications/initialized▶ (header: mcp-session-id: <ID>)
│◀── 202 Accepted ───────────────────────│
│ │
│── POST /…/mcp tools/call ─────────────▶│ (header: mcp-session-id: <ID>)
│◀── 200 + result ───────────────────────│
│ │
│── POST /…/mcp tools/call … ───────────▶│
│◀── 200 + result ───────────────────────│
│ (repeat as needed) │
The JSON and SSE endpoints maintain independent session spaces. A session
id obtained from /json/mcp only works against /json/mcp, and similarly for
SSE.
5. curl / bash — sample calls (JSON and SSE)
Reusable setup for both modes:
JSON_URL="https://mcpserver-production-dd31.up.railway.app/json/mcp"
SSE_URL="https://mcpserver-production-dd31.up.railway.app/sse/mcp"
CT="Content-Type: application/json"
ACCEPT="Accept: application/json, text/event-stream"
5.1 initialize → session id
JSON
# Capture the mcp-session-id header from the initialize response
SID_JSON=$(curl -s -D - -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"1.0"}}}' \
| grep -i "mcp-session-id:" | awk '{print $2}' | tr -d '\r\n')
echo "json session: $SID_JSON"
SSE
SID_SSE=$(curl -s -D - -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"1.0"}}}' \
| grep -i "mcp-session-id:" | awk '{print $2}' | tr -d '\r\n')
echo "sse session: $SID_SSE"
5.2 notifications/initialized
Same request shape for both — only the URL differs.
JSON
curl -s -o /dev/null -w "notify HTTP %{http_code}\n" -X POST "$JSON_URL" \
-H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
-d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
SSE
curl -s -o /dev/null -w "notify HTTP %{http_code}\n" -X POST "$SSE_URL" \
-H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
-d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
5.3 tools/list
JSON
curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
-d '{"jsonrpc":"2.0","id":10,"method":"tools/list"}'
Sample reply (truncated):
{"jsonrpc":"2.0","id":10,"result":{"tools":[{"name":"search_locations", ...}, ...]}}
SSE
curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
-d '{"jsonrpc":"2.0","id":10,"method":"tools/list"}'
Sample reply (SSE framing — parse the data: line as JSON):
event: message
data: {"jsonrpc":"2.0","id":10,"result":{"tools":[{"name":"search_locations", ...}, ...]}}
5.4 tools/call — current weather for Karlsruhe
JSON
curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_current_weather","arguments":{"location":"Karlsruhe, Germany"}}}'
SSE
curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_current_weather","arguments":{"location":"Karlsruhe, Germany"}}}'
5.5 resources/templates/list
JSON
curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
-d '{"jsonrpc":"2.0","id":11,"method":"resources/templates/list"}'
SSE
curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
-d '{"jsonrpc":"2.0","id":11,"method":"resources/templates/list"}'
5.6 resources/read — briefing bundle
JSON
curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
-d '{"jsonrpc":"2.0","id":20,"method":"resources/read","params":{"uri":"weather://briefing/Karlsruhe, Germany"}}'
SSE
curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
-d '{"jsonrpc":"2.0","id":20,"method":"resources/read","params":{"uri":"weather://briefing/Karlsruhe, Germany"}}'
5.7 prompts/list
JSON
curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
-d '{"jsonrpc":"2.0","id":12,"method":"prompts/list"}'
SSE
curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
-d '{"jsonrpc":"2.0","id":12,"method":"prompts/list"}'
5.8 prompts/get
JSON
curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
-d '{"jsonrpc":"2.0","id":30,"method":"prompts/get","params":{"name":"weather_briefing","arguments":{"location":"Karlsruhe, Germany","audience":"pilots"}}}'
SSE
curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
-d '{"jsonrpc":"2.0","id":30,"method":"prompts/get","params":{"name":"weather_briefing","arguments":{"location":"Karlsruhe, Germany","audience":"pilots"}}}'
6. Node-RED — function code for HTTP Request nodes
Two variants of the flow are provided: one targeting the JSON endpoint and one targeting the SSE endpoint. The session / init sequence is identical; the only differences are the URL and how you parse the response body.
6.1 Flow shape (both variants)
inject
→ [Fn1 init req] → [HTTP 1: initialize]
→ [Fn2 notify req] → [HTTP 2: notify] (body is empty, status 202)
→ [Fn3 tools/call] → [HTTP 3: tools/call]
→ [Fn4 unwrap]
→ debug
HTTP Request node settings:
- Method:
- use msg.method - - URL:
- use msg.url - - JSON variant: HTTP 1 and HTTP 3 return a parsed JSON object; HTTP 2 returns a UTF-8 string.
- SSE variant: HTTP 1, HTTP 2, and HTTP 3 all return a UTF-8 string (SSE framing has to be parsed manually).
After each HTTP Request node, msg.headers holds the response headers,
so Fn2 can pull mcp-session-id out of it.
6.2 JSON variant — function code
Fn1 — build initialize request
msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/json/mcp";
msg.headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream"
};
msg.payload = {
jsonrpc: "2.0",
id: 1,
method: "initialize",
params: {
protocolVersion: "2025-06-18",
capabilities: {},
clientInfo: { name: "node-red", version: "1.0" }
}
};
return msg;
Fn2 — extract session id, build notifications/initialized
const sessionId = msg.headers && msg.headers["mcp-session-id"];
if (!sessionId) {
node.error("No mcp-session-id header in initialize response", msg);
return null;
}
flow.set("mcpSessionIdJson", sessionId);
msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/json/mcp";
msg.headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"mcp-session-id": sessionId
};
msg.payload = {
jsonrpc: "2.0",
method: "notifications/initialized"
};
return msg;
Fn3 — call get_current_weather for Karlsruhe
const sessionId = flow.get("mcpSessionIdJson");
msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/json/mcp";
msg.headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"mcp-session-id": sessionId
};
msg.payload = {
jsonrpc: "2.0",
id: 2,
method: "tools/call",
params: {
name: "get_current_weather",
arguments: { location: "Karlsruhe, Germany" }
}
};
return msg;
Fn4 — unwrap the MCP envelope (JSON variant)
// msg.payload is the parsed JSON envelope from HTTP 3.
const text = msg.payload?.result?.content?.[0]?.text;
if (!text) {
node.error("Unexpected MCP response shape", msg);
return null;
}
msg.payload = JSON.parse(text);
// msg.payload.current.temperature_2m, .relative_humidity_2m, .wind_speed_10m, …
return msg;
6.3 SSE variant — function code
The requests are identical in structure; only the URL and the Fn4 parser differ. HTTP Request nodes must return a UTF-8 string for all three steps.
Fn1 — build initialize request (SSE)
msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/sse/mcp";
msg.headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream"
};
msg.payload = {
jsonrpc: "2.0",
id: 1,
method: "initialize",
params: {
protocolVersion: "2025-06-18",
capabilities: {},
clientInfo: { name: "node-red", version: "1.0" }
}
};
return msg;
Fn2 — extract session id, build notifications/initialized (SSE)
const sessionId = msg.headers && msg.headers["mcp-session-id"];
if (!sessionId) {
node.error("No mcp-session-id header in initialize response", msg);
return null;
}
flow.set("mcpSessionIdSse", sessionId);
msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/sse/mcp";
msg.headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"mcp-session-id": sessionId
};
msg.payload = {
jsonrpc: "2.0",
method: "notifications/initialized"
};
return msg;
Fn3 — call get_current_weather for Karlsruhe (SSE)
const sessionId = flow.get("mcpSessionIdSse");
msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/sse/mcp";
msg.headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"mcp-session-id": sessionId
};
msg.payload = {
jsonrpc: "2.0",
id: 2,
method: "tools/call",
params: {
name: "get_current_weather",
arguments: { location: "Karlsruhe, Germany" }
}
};
return msg;
Fn4 — parse SSE frame, then unwrap the MCP envelope
// msg.payload is a raw SSE string like:
// event: message
// data: {"jsonrpc":"2.0","id":2,"result":{...}}
//
const raw = typeof msg.payload === "string" ? msg.payload : "";
const dataLine = raw.split(/\r?\n/).find(l => l.startsWith("data:"));
if (!dataLine) {
node.error("No data: frame in SSE response", msg);
return null;
}
const envelope = JSON.parse(dataLine.slice(5).trim());
const text = envelope?.result?.content?.[0]?.text;
msg.payload = text ? JSON.parse(text) : envelope;
return msg;
6.4 Browse (discovery) — swap into Fn3
Replace Fn3 with this to list tools/resources/prompts. Works for both variants — just use the matching URL and session-id key.
// Replace `method` with one of:
// "tools/list"
// "resources/templates/list"
// "prompts/list"
const sessionId = flow.get("mcpSessionIdJson"); // or "mcpSessionIdSse"
msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/json/mcp"; // or /sse/mcp
msg.headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"mcp-session-id": sessionId
};
msg.payload = {
jsonrpc: "2.0",
id: 10,
method: "tools/list"
};
return msg;
Matching unwrap for list results — JSON variant:
const r = msg.payload?.result;
msg.payload = r?.tools ?? r?.resourceTemplates ?? r?.prompts ?? r ?? msg.payload;
return msg;
Matching unwrap for list results — SSE variant:
const raw = typeof msg.payload === "string" ? msg.payload : "";
const dataLine = raw.split(/\r?\n/).find(l => l.startsWith("data:"));
const envelope = dataLine ? JSON.parse(dataLine.slice(5).trim()) : null;
const r = envelope?.result;
msg.payload = r?.tools ?? r?.resourceTemplates ?? r?.prompts ?? r ?? envelope;
return msg;
6.5 Tips
- Sessions live per-endpoint and per-variant. The JSON and SSE endpoints have independent session spaces, so you need to init each one separately.
- After initializing, you can skip Fn1/Fn2/HTTP1/HTTP2 on subsequent injects
and run only Fn3→HTTP3→Fn4 — the session id is in
flow.context. - If a later call errors out with a session-related message, re-run the full init sequence once.
msg.headersis replaced by the HTTP Request node with the response headers, so extract anything you need (likemcp-session-id) in the immediately following function node.- To call a different tool, change
nameandargumentsin Fn3. The other tools aresearch_locations(query),get_forecast(location, days), andget_severe_alerts(location).
7. Integrating with MCP-native clients
Any client that speaks MCP Streamable HTTP natively can point at either endpoint. Use the SSE endpoint by default (it matches what every MCP SDK expects); use the JSON endpoint only if you need plain-JSON bodies for debugging or HTTP tooling.
{
"mcpServers": {
"weather-sse": {
"type": "streamable-http",
"url": "https://mcpserver-production-dd31.up.railway.app/sse/mcp"
},
"weather-json": {
"type": "streamable-http",
"url": "https://mcpserver-production-dd31.up.railway.app/json/mcp"
}
}
}
No auth headers needed — the server is public.
8. Notes and gotchas
- No API key is required anywhere. Open-Meteo is free and keyless; the MCP server itself is unauthenticated.
- Weather codes in responses are WMO codes
(e.g.
0clear,3overcast,61light rain,95thunderstorm). - Units are always included under
units/daily_unitsin the payload, so consumers never have to guess (e.g.°C,%,km/h,mm). - Severe alerts are synthesized — Open-Meteo does not expose government
alert feeds. Thresholds used: precipitation ≥ 25 mm/day, max temp ≥ 38 °C,
min temp ≤ −15 °C. Adjust in
weather_client.severe_alerts()if needed. - Location parsing uses Open-Meteo's geocoding API, which is forgiving
(
"Karlsruhe"alone works, but"Karlsruhe, Germany"removes ambiguity). - Session lifetime is managed server-side per endpoint. If a session goes stale, re-initialize.
- SSE framing is a single-line
data:prefix followed by\n\n. The server emits oneevent: messageframe per response; multi-frame streams are possible in theory but not used by the current tools.