Open-Meteo Model Context Protocol Server

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... FromCjs is not supported.

  cause Attempting to import `open-meteo-mcp-server` using CommonJS `require()` syntax in a CommonJS module.
  fix This package is an ES Module. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import` statements. If you must use CommonJS, consider dynamic `import()`: `const module = await import('open-meteo-mcp-server');`

• TypeError: createMcpServer is not a function

  cause Incorrectly importing `createMcpServer` as a default export or from a wrong path.
  fix Ensure `createMcpServer` is imported as a named export: `import { createMcpServer } from 'open-meteo-mcp-server';`

• Error: Your Node.js version is too old. This package requires Node.js >= 22.0.0.

  cause The installed Node.js version does not meet the minimum requirement specified in `package.json`.
  fix Update your Node.js installation to version 22.0.0 or newer. Tools like `nvm` (Node Version Manager) can help manage multiple Node.js versions.

• ZodError: [ { "code": "invalid_type", "expected": "string", "received": "undefined", "path": [ "latitude" ], "message": "Required" } ]

  cause An incoming request to the MCP server did not conform to the expected Zod schema for the Open-Meteo API, missing a required parameter like `latitude`.
  fix Verify that your client-side requests include all necessary parameters as defined by the Open-Meteo API documentation and the MCP server's validation schemas. Consult the `open-meteo-mcp` GitHub repository for the latest schema definitions.

Warnings

• breaking The package requires Node.js version 22.0.0 or higher. Older Node.js versions will not be able to run this server.
  Fix: Upgrade your Node.js environment to version 22.0.0 or later using a tool like nvm (Node Version Manager).
• breaking Introduced significant security features including cryptographic session IDs, authentication middleware, rate limiting, and trusted-proxy IP validation. While these are enhancements, they may require configuration and could alter how the server responds to unauthenticated/unauthorized requests or high traffic.
  Fix: Review the documentation for `v1.4.0` regarding security configurations. Ensure your environment variables like `TRUSTED_PROXY_CIDR` are correctly set if the server is behind a proxy to ensure correct IP-based security features function as intended.
• gotcha Various fixes for schema inconsistencies in Open-Meteo API requests (e.g., `ForecastModelsSchema`, `ArchiveHourlyVariablesSchema`, `past_days` constraints). Clients making requests to the MCP server that rely on outdated or incorrect schema assumptions might encounter Zod validation errors.
  Fix: Keep the `open-meteo-mcp-server` package updated to the latest version to ensure alignment with current Open-Meteo API schemas. When developing clients, refer to the Open-Meteo API documentation and the server's expected request bodies.
• gotcha HTTP errors from upstream Axios calls are now mapped to typed MCP error responses. Clients that previously parsed raw Axios error structures may need to update their error handling logic to correctly interpret the new, structured error formats.
  Fix: Adjust client-side error handling to expect structured MCP error responses instead of raw HTTP client (Axios) errors when interacting with the server. Refer to the Model Context Protocol specification for expected error formats.

Install

• npm install open-meteo-mcp-server npm
• yarn add open-meteo-mcp-server yarn
• pnpm add open-meteo-mcp-server pnpm

Imports

• createMcpServer
  wrong:

  const { createMcpServer } = require('open-meteo-mcp-server');

  correct:

  import { createMcpServer } from 'open-meteo-mcp-server';

  This package is an ESM module and requires Node.js >= 22.0.0. Use `import` syntax.
• startMcpServer
  wrong:

  import startMcpServer from 'open-meteo-mcp-server';

  correct:

  import { startMcpServer } from 'open-meteo-mcp-server';

  `startMcpServer` is a named export, not a default export. It creates and starts the server instance.
• McpServerOptions

  import type { McpServerOptions } from 'open-meteo-mcp-server';

  Import `McpServerOptions` as a type for programmatic configuration of the server. It's available as a named export.

Quickstart

This quickstart demonstrates how to programmatically start the Open-Meteo MCP server using `startMcpServer`, configuring its host and port through environment variables or defaults.

import { startMcpServer } from 'open-meteo-mcp-server';

async function runServer() {
  const port = parseInt(process.env.PORT ?? '3000', 10);
  const host = process.env.HOST ?? '0.0.0.0';
  console.log(`Starting Open-Meteo MCP Server on ${host}:${port}...`);

  try {
    const server = await startMcpServer({
      port,
      host,
      // Optional: Configure trusted proxies for security features
      // trustedProxy: process.env.TRUSTED_PROXY_CIDR || undefined,
      // Optional: Configure rate limiting
      // rateLimitWindowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS || '60000', 10),
      // rateLimitMax: parseInt(process.env.RATE_LIMIT_MAX || '100', 10),
      // Optional: Specify Open-Meteo API URLs if not default
      // openMeteoApiUrl: process.env.OPEN_METEO_API_URL || 'https://api.open-meteo.com'
    });
    console.log(`Server started successfully. MCP URL: http://${host}:${port}/mcp`);
  } catch (error) {
    console.error('Failed to start MCP server:', error);
    process.exit(1);
  }
}

// To run this script, ensure your Node.js version is >= 22.0.0
// You can also run it directly via npx: npx -y -p open-meteo-mcp-server open-meteo-mcp-server
runServer();