Setup Guide

Get a key with npx -y @smarterweather/mcp-onboarding@latest login (human) or trial (no account). The key goes to the project .env, and the bridge reads it via envFile / SMARTERWEATHER_ENV_FILE / ./.env. No config below holds the key.

One-click install

The fastest path — installs the stdio bridge into your client. No key yet? Run login or trial in the project first (see Prerequisites for the other ways). Each host's per-project config is below.

Prerequisites

• Node.js 22+ (the stdio bridge runs with npx)
• An API key, from one of:
  • login or the Developer Dashboard: needs a free SmarterWeather account (create one)
  • trial: no account needed
  • create_api_key on the onboarding MCP: needs a free account and an OAuth sign-in. The one-click onboarding install connects anonymously (discovery tools only), so add SMARTERWEATHER_ONBOARDING_AUTH=required to its env for the stdio bridge to sign you in first

Claude Desktop

Add the following to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS). Claude Desktop has no project folder, so point the bridge at the project .env with an absolute path. The config holds a path, never the key:

{
  "mcpServers": {
    "smarterweather": {
      "command": "npx",
      "args": [
        "-y",
        "@smarterweather/mcp-weather@latest"
      ],
      "env": {
        "SMARTERWEATHER_ENV_FILE": "/absolute/path/to/your/project/.env"
      }
    }
  }
}

Claude Code

No --env flag, so no key lands in ~/.claude.json. Run login or trial in the project root, then run Claude Code from the project root:

claude mcp add smarterweather -- npx -y @smarterweather/mcp-weather@latest

Cursor

For a manual merge into the project .cursor/mcp.json (envFile loads the project's .env, so no key goes in the config):

{
  "mcpServers": {
    "smarterweather": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@smarterweather/mcp-weather@latest"
      ],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

VS Code

The project .vscode/mcp.json uses the servers key; envFile works the same way:

{
  "servers": {
    "smarterweather": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@smarterweather/mcp-weather@latest"
      ],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Without a key

OAuth sign-in to the weather MCP isn't available to generic MCP clients yet, so use an API key. With no key, tool calls return x402 payment requirements; the discovery tools stay free.

Generic MCP Client

Any stdio-capable client can run the same bridge. It reads the key from SMARTERWEATHER_API_KEY, then SMARTERWEATHER_ENV_FILE, then ./.env:

npx -y @smarterweather/mcp-weather@latest

Do not append @preview — latest is the GA bridge. The hosted weather tools live at https://mcp.smarterweather.com; the npm package is a thin stdio-to-Streamable-HTTP proxy.

Remote HTTP

Clients that support remote MCP servers with headers can connect to https://mcp.smarterweather.com directly (Cursor syntax shown). The root serves the default toolsets; to add others, see Connecting a toolset:

{
  "mcpServers": {
    "smarterweather": {
      "url": "https://mcp.smarterweather.com",
      "headers": {
        "Authorization": "Bearer ${env:SMARTERWEATHER_API_KEY}"
      }
    }
  }
}

Cursor and Claude Code (.mcp.json, written ${SMARTERWEATHER_API_KEY}) read the key from the client's environment. VS Code instead prompts for it once: use type: "http" with a promptString input marked password: true and Bearer ${input:<id>}. Either way the key is never pasted into the file.

Apps launched from the Dock, Start menu or a desktop shortcut don't see exports from ~/.zshrc or ~/.bashrc. An unset variable sends an empty Bearer header, which fails with a 401 (it is not treated as keyless). Start the client from a shell that has the variable set, or use the stdio bridge with envFile above. envFile doesn't apply to remote servers, so the stdio bridge stays the default for desktop hosts.

Verify the Connection

After configuration, try a simple prompt in your AI client:

What's the weather in Denver, CO right now?

The AI should invoke search_locations (or accept location on the tool) and get_forecast to answer with real-time weather data.