Weather API MCP Server Template (TypeScript + Zod + STDIO Transport)

Stop wasting 6 hours wiring MCP servers by hand. Start shipping a fully working Weather API MCP server in under 10 minutes.

You know the pain: you try to hook an MCP server to a weather API and everything breaks. STDIO blocks the process, Zod schemas don’t match tool calls, and the fetch logic fails silently with no useful errors. You burn hours debugging plumbing instead of testing your agent.

This template gives you a complete TypeScript + Zod MCP Weather Server with STDIO transport already wired, validated, and production‑ready. Every file is configured, typed, and tested so you can drop in your API key, run one command, and immediately use weather tools inside your agent environment.

What’s Included:
- Fully wired MCP STDIO transport with clean shutdown logic
- Zod‑typed schemas for current conditions and forecast tools
- Error‑safe fetch wrapper with retries, timeouts, and rate‑limit handling
- Input validation that blocks malformed queries and prevents JSON injection
- API key guard that fails fast and logs safely
- Weather client module with typed responses for consistent agent behavior
- End‑to‑end example server that works out of the box with Claude and other agents
- 14 commented files showing exactly where to customize and extend

Built from patterns used in real agent deployments where stability matters. The code reflects failures observed across dozens of AI tool integrations—STDIO stalls, schema mismatches, and unhandled API errors—so you avoid the issues that slow down most indie builders.

Who This Is For:
- Indie hackers testing AI agents and needing a plug‑and‑play weather tool
- Engineers tired of rebuilding MCP server scaffolding from scratch
- Agent researchers who want predictable, typed tool behavior for experiments

Who This Is NOT For:
- Anyone looking for a generic MCP tutorial instead of a ready server
- Teams that already maintain a stable internal MCP server framework

If this doesn’t save you at least 4 hours of setup time, reach out for a full refund.

What's Included (12 files)

• src-utils-env-validation.ts---Zod-powered-validation-of-API-keys-and-environment-variables-(fails-fast-on-startup)
• scripts-dev-stdio-runner.js---Local-STDIO-runner-that-simulates-an-AI-agent-calling-the-MCP-server
• TROUBLESHOOTING.md---Fixes-for-common-MCP-issues-like-STDIO-hangs,-schema-mismatches,-and-API-rate-limit-failures
• src-weather-client.ts---Typed-wrapper-around-the-external-weather-API-with-retry-and-rate‑limit-handling
• src-tools-get-current-weather.ts---MCP-tool-that-fetches-real-time-weather-data-using-validated-parameters
• tests-weather-server.test.ts---End-to-end-tests-for-MCP-tool-invocation-via-STDIO-transport
• src-utils-safe-fetch.ts---Production-safe-fetch-wrapper-with-timeouts,-exponential-backoff,-and-JSON-parse-protection
• DEPLOY-NOTES.md---Guidance-for-deploying-MCP-servers-(PM2-setup,-logging,-env-hardening,-and-reliability-tips)
• src-server.ts---Fully-working-MCP-server-with-STDIO-transport-and-request-routing
• SETUP-GUIDE.md---Clear-10-minute-setup-guide-including-environment-setup,-running-STDIO-transport,-and-test-instructions
• src-schemas-weather-schemas.ts---Zod-schemas-for-weather-queries,-responses,-errors,-and-MCP-tool-definitions
• src-tools-get-forecast.ts---MCP-tool-that-returns-multi-day-forecast-with-safe-normalization-of-vendor-differences