MCP Server - iklim.co API Documentation

This guide is intended for developers and technically proficient users. Setting up the MCP server requires Node.js, a terminal, and basic familiarity with configuration files.

57 Tools

Every iklim.co API capability is exposed as an MCP tool — lightning, thunderstorm, precipitation, forecast, alarms, and more.

Auto Auth

JWT tokens are acquired and refreshed automatically. Just provide your credentials and the server handles the rest.

HMAC-Signed

Every request is signed with HMAC-SHA256. Credentials never travel in plain text and replay attacks are blocked with a per-request nonce.

Overview

The iklim.co MCP Server implements the Model Context Protocol and exposes the full iklim.co REST API as 57 tools across 9 categories. Any MCP-compatible AI client (Claude, OpenClaw, and others) can query live weather data, manage alarms, and handle user accounts through natural language.

Category	Tools	Scope
⚡ Lightning	2	Lightning strike data
🌪️ Thunderstorm	3	Thunderstorm cell tracking
🌧️ Precipitation	2	Radar precipitation data
🌤️ Forecast	3	Hourly / daily / current weather
👤 Auth & User	11	Authentication and user management
🏢 Account	8	Account and subscription management
📍 Point Alarms	6	GPS-based alert subscriptions
🗺️ Geo Alarms	12	Boundary-based alerts + city/district/neighborhood catalog
📅 Forecast Alarms	10	Threshold-based forecast alerts + city/district catalog
Total	57

Requirements

Node.js >= 18 (ES2022 support required)
npm >= 9
iklim.co API credentials: HMAC secret, username, and password

Installation

The source code is publicly available at git.tarla.io/iklim.co/mcp-server.

git clone https://git.tarla.io/iklim.co/mcp-server.git
cd mcp-server
npm install
npm run build

Environment Variables

The following variables must be set before the server starts. For local development, create a .env file in the mcp-server directory (already in .gitignore):

# .env
IKLIM_ENV=test                     # prod | test | local  (used when IKLIM_BASE_URL is not set)
IKLIM_BASE_URL=                    # Optional. Overrides IKLIM_ENV when set
IKLIM_HMAC_SECRET=<secret>         # Required. HMAC-SHA256 key for request signing
IKLIM_USERNAME=<email>             # Required. API account e-mail
IKLIM_PASSWORD=<password>          # Required. API account password
IKLIM_TOKEN_STORE_PATH=            # Optional. Path for persisting access/refresh tokens
IKLIM_HTTP_LOG_PATH=               # Optional. API request log file path
IKLIM_HTTP_LOG_MAX_BYTES=5242880   # Optional. Rotate threshold in bytes (default: 5 MB)
IKLIM_HTTP_LOG_MAX_FILES=5         # Optional. Number of rotated files to keep
IKLIM_HTTP_LOG_REQUEST_BODY_MAX_BYTES=16384   # Optional. Request body log size limit
IKLIM_HTTP_LOG_RESPONSE_BODY_MAX_BYTES=16384  # Optional. Response body log size limit

Base URL by environment:

`IKLIM_ENV`	URL
`prod`	`https://api.iklim.co`
`test`	`https://api-test.iklim.co`
`local`	`http://localhost:8080`

When IKLIM_HTTP_LOG_PATH is set, every API call is written as a single-line JSON log entry. Sensitive fields (Authorization, X-Signature, password, token, etc.) are automatically masked.

Build & Run

# Compile TypeScript (outputs to dist/)
npm run build

# Start the compiled server
npm start

# Development mode — no build step required
npm run dev

A successful start prints:

iklim.co MCP server running

The server communicates over stdio transport. It is designed to be managed by an MCP client, not run interactively in a terminal.

MCP Client Configuration

Claude CLI (`.mcp.json`)

Place a .mcp.json file in your project root. Claude CLI picks it up automatically:

{
  "mcpServers": {
    "iklim": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "IKLIM_ENV": "test",
        "IKLIM_HMAC_SECRET": "<secret>",
        "IKLIM_USERNAME": "<email>",
        "IKLIM_PASSWORD": "<password>"
      }
    }
  }
}

To register the server globally, add the same mcpServers block to ~/.claude/settings.json.

OpenClaw

The openclaw mcp set command does not support a separate env flag — pass everything as a single JSON object:

openclaw mcp set iklim '{"type":"stdio","command":"node","args":["/absolute/path/to/mcp-server/dist/index.js"],"env":{"IKLIM_ENV":"test","IKLIM_HMAC_SECRET":"<secret>","IKLIM_USERNAME":"<email>","IKLIM_PASSWORD":"<password>"}}'

Or edit ~/.openclaw/openclaw.json directly:

{
  "mcp": {
    "iklim": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "IKLIM_ENV": "test",
        "IKLIM_HMAC_SECRET": "<secret>",
        "IKLIM_USERNAME": "<email>",
        "IKLIM_PASSWORD": "<password>"
      }
    }
  }
}

Other MCP Clients

Any client that supports the MCP stdio standard can connect. Required parameters:

Parameter	Value
`transport`	`stdio`
`command`	`node`
`args`	`["<absolute path to dist/index.js>"]`
`env`	The four variables above

Tool Catalog

⚡ Lightning

Tool	Description
`get_lightnings_within`	Queries lightning strikes within a circular area defined by center coordinates and radius
`get_lightnings_page`	Returns paginated lightning data for a time interval

🌪️ Thunderstorm

Tool	Description
`get_thunderstorms_within`	Queries thunderstorm cells within a circular area
`get_thunderstorms_page`	Returns paginated thunderstorm data for a time interval
`get_thunderstorm_details`	Fetches historical details for a specific storm event by `eventId`

🌧️ Precipitation

Tool	Description
`get_precipitations_within`	Queries radar precipitation data within a circular area; optionally filter by `intensityThreshold`
`get_precipitations_page`	Returns paginated precipitation data; `intensityThreshold` is required

Intensity levels (lowest → highest): DRIZZLE < LIGHT < MODERATE < HEAVY < VERY_HEAVY < EXTREME

🌤️ Forecast

Tool	Description
`get_hourly_forecast`	Hourly forecasts for 1–14 days; supports 53 selectable metrics
`get_daily_forecast`	Daily aggregate forecasts; same parameters as hourly (excluding solar panel fields)
`get_current_weather`	Most recent weather observation for a coordinate

53 supported forecast metrics

WEATHER_ICON, TEMPERATURE, APPARENT_TEMPERATURE, DEW_POINT_TEMPERATURE, HUMIDITY, CLOUD_COVER, CLOUD_COVER_LOW, CLOUD_COVER_MID, CLOUD_COVER_HIGH, WIND_SPEED, WIND_GUST, WIND_DIRECTION, WIND_SPEED_AT_100M, WIND_DIRECTION_AT_100M, PRECIPITATION, RAIN, SHOWERS, SNOWFALL, SNOW_DEPTH, PRECIPITATION_PROBABILITY, WEATHER_CODE, PRESSURE_MSL, SURFACE_PRESSURE, VISIBILITY, EVAPOTRANSPIRATION, ET0_FAO_EVAPOTRANSPIRATION, VAPOUR_PRESSURE_DEFICIT, CAPE, LIFTED_INDEX, CONVECTIVE_INHIBITION, SUNSHINE_DURATION, SHORTWAVE_RADIATION, DIRECT_RADIATION, DIFFUSE_RADIATION, DIRECT_NORMAL_IRRADIANCE, GLOBAL_TILTED_IRRADIANCE, TERRESTRIAL_RADIATION, SHORTWAVE_RADIATION_INSTANT, DIRECT_RADIATION_INSTANT, DIFFUSE_RADIATION_INSTANT, DIRECT_NORMAL_IRRADIANCE_INSTANT, GLOBAL_TILTED_IRRADIANCE_INSTANT, TERRESTRIAL_RADIATION_INSTANT, SOIL_TEMPERATURE_0CM, SOIL_TEMPERATURE_6CM, SOIL_TEMPERATURE_18CM, SOIL_TEMPERATURE_54CM, SOIL_MOISTURE_0_TO_1CM, SOIL_MOISTURE_1_TO_3CM, SOIL_MOISTURE_3_TO_9CM, SOIL_MOISTURE_9_TO_27CM, SOIL_MOISTURE_27_TO_81CM, IS_DAY

👤 Auth & User

Tool	Description
`auth_register`	Creates a new user account
`auth_logout`	Invalidates the current JWT token
`user_get_me`	Returns the authenticated user’s profile
`user_get`	Returns a user’s details by `userId`
`user_create`	(Admin) Creates a new user with `roles` and `status`
`user_update`	(Admin) Updates user fields by `userId`
`user_list`	Returns a paginated user list; filterable by `roles`, `status`
`user_unblock`	Unblocks a blocked user
`user_change_password`	Changes password with `oldPassword` and `newPassword`
`user_password_reset_request`	Sends a password reset e-mail
`user_password_reset`	Updates password using a reset token

🏢 Account

Tool	Description
`account_get`	Returns account details by `userId`
`account_create`	Creates a new account (`INDIVIDUAL` or `ORGANIZATION`)
`account_update`	Updates account fields by `accountId`
`account_activation_request`	Sends an activation e-mail
`account_activate`	Activates the account using an e-mail verification token
`account_phone_activation_request`	Sends an SMS verification code
`account_activate_phone`	Verifies the phone number using an SMS token
`account_update_subscription`	Changes the subscription plan

📍 Point Alarms

GPS-coordinate-based alert subscriptions for events within a configurable radius.

Tool	Description
`point_alarm_register`	Creates a new point alarm
`point_alarm_update`	Updates an existing alarm
`point_alarm_delete`	Deletes an alarm
`point_alarm_get_by_id`	Returns a single alarm’s details
`point_alarm_get_by_recipient`	Lists all alarms for a recipient
`point_alarm_list`	Paginated alarm list; filterable by `recipientIds`

🗺️ Geo Alarms

Administrative boundary, polygon, or H3 address-based alert subscriptions. Three boundary types are supported:

// Administrative boundary
{ "type": "ADMINISTRATIVE", "cityId": 6, "districtId": 60 }

// Polygon
{ "type": "POLYGON", "polygon": { "exterior": [{"lat": 39.9, "lng": 32.8}, ...] } }

// H3 cell index
{ "type": "H3INDEX", "h3Address": "8f2830828052d25" }

CRUD tools (geo_alarm_register, geo_alarm_update, geo_alarm_delete, geo_alarm_get_by_id, geo_alarm_get_by_recipient, geo_alarm_list) share the same signature as Point Alarms. Location catalog:

Tool	Description
`geo_alarm_list_cities`	Lists all cities
`geo_alarm_get_city`	Returns city details by `cityId`
`geo_alarm_list_districts`	Lists districts by `cityId`
`geo_alarm_get_district`	Returns district details by `districtId`
`geo_alarm_list_neighborhoods`	Lists neighborhoods by `districtId`
`geo_alarm_get_neighborhood`	Returns neighborhood details by `neighborhoodId`

📅 Forecast Alarms

Threshold-based alerts delivered at 04:00 UTC (morning) or 16:00 UTC (evening). Threshold parameters:

Parameter	Values
`precipitationThreshold`	Numeric value in mm
`snowFallThreshold`	`LIGHT` \| `MODERATE` \| `HEAVY`
`windGustThreshold`	`STRONG_WIND` \| `STORM` \| `SEVERE_STORM` \| `HURRICANE`
`hotTemperatureThreshold`	`HOT_SNAP` \| `HEAVY_HOT_SNAP` \| `EXTREME_HOT_SNAP`
`coldTemperatureThreshold`	`COLD_SNAP` \| `HEAVY_COLD_SNAP` \| `EXTREME_COLD_SNAP`

CRUD tools follow the same signature as Point Alarms. Additional location catalog tools: forecast_alarm_list_cities, forecast_alarm_get_city, forecast_alarm_list_districts, forecast_alarm_get_district.

Architecture

src/
├── index.ts          # MCP server bootstrap, tool routing
├── config.ts         # Environment variable parsing
├── auth.ts           # JWT token management (auto-refresh)
├── client.ts         # HTTP API client (HMAC signing)
├── security.ts       # HMAC-SHA256, nonce, idempotency key
└── tools/
    ├── lightnings.ts
    ├── thunderstorms.ts
    ├── precipitations.ts
    ├── forecasts.ts
    ├── auth.ts
    ├── accounts.ts
    ├── point-alarms.ts
    ├── geo-alarms.ts
    └── forecast-alarms.ts

Request flow:

MCP Client
    │
    ▼
index.ts  (CallToolRequestSchema)
    │
    ▼
tools/<category>.ts  ← Zod validation
    │
    ▼
client.ts  (apiGet / apiPost / apiPatch / apiDelete)
    │  ├── auth.ts → get valid JWT (auto-refresh if needed)
    │  └── security.ts → generate HMAC-SHA256 signature
    │
    ▼
iklim.co REST API

Authentication & Security

Every API interaction uses two independent security layers: JWT-based authentication and HMAC-SHA256 request signing. Both are applied to every request.

Automatic Auth Flow

The server logs in automatically on the first tool call. No manual login step is needed.

First tool call
    │
    ▼
getValidAccessToken()          ← auth.ts
    │
    ├─ No token state → login()
    │       POST /v1/auth/login  { username, password }
    │       ← { accessToken, refreshToken }
    │       Decode JWT payload → calculate expiry
    │       Save to tokenState
    │
    ├─ accessToken expiring soon (< 30 s) → refresh()
    │       POST /v1/auth/refresh  { refreshToken }
    │       ← { accessToken, refreshToken }
    │       Update tokenState
    │
    └─ accessToken valid → return directly

The login and refresh endpoints do not include an Authorization: Bearer header — they are authenticated by HMAC signature alone.

HTTP Request Headers

Header	Value	Notes
`Content-Type`	`application/json`	Fixed
`Authorization`	`Bearer <accessToken>`	Normal API requests only; omitted for login/refresh
`X-Signature`	hex string	HMAC-SHA256 signature
`X-Timestamp`	Unix epoch (ms)	`Date.now()` as a string
`X-Nonce`	UUID v4	Unique per request — prevents replay attacks
`X-Idempotency-Key`	UUID v4	`POST`, `PUT`, `PATCH`, and `DELETE` requests

HMAC-SHA256 Signature

The X-Signature value is the HMAC-SHA256 of four components joined by |:

data_to_sign = "METHOD|PATH_WITH_QUERY|TIMESTAMP|BODY"
X-Signature  = HMAC-SHA256(data_to_sign, IKLIM_HMAC_SECRET) → hex

Example — GET request:

METHOD    = "GET"
PATH      = "/v1/users?pageNumber=0&pageSize=10"
TIMESTAMP = "1774349677000"
BODY      = ""   ← empty for GET

data_to_sign = "GET|/v1/users?pageNumber=0&pageSize=10|1774349677000|"
X-Signature  = HMAC-SHA256(data_to_sign, secret) → "a3f9c2..."

Example — POST request:

METHOD    = "POST"
PATH      = "/v1/lightnings/within"
TIMESTAMP = "1774349677000"
BODY      = '{"center":{"lat":39.87,"lng":32.74},"radius":50000,...}'

data_to_sign = "POST|/v1/lightnings/within|1774349677000|{\"center\":...}"
X-Signature  = HMAC-SHA256(data_to_sign, secret) → "7be41d..."

Security Recommendations

Never commit IKLIM_HMAC_SECRET or IKLIM_PASSWORD to source control or git history
In production, use system environment variables or a secrets manager instead of a .env file
Use separate credentials for each environment (prod / test / local)
Rotate the HMAC secret regularly

57 Tools

Auto Auth

HMAC-Signed

​Overview

​Requirements

​Installation

​Environment Variables

​Build & Run

​MCP Client Configuration

​Claude CLI (.mcp.json)

​OpenClaw

​Other MCP Clients

​Tool Catalog

​⚡ Lightning

​🌪️ Thunderstorm

​🌧️ Precipitation

​🌤️ Forecast

​👤 Auth & User

​🏢 Account

​📍 Point Alarms

​🗺️ Geo Alarms

​📅 Forecast Alarms

​Architecture

​Authentication & Security

​Automatic Auth Flow

​HTTP Request Headers

​HMAC-SHA256 Signature

​Security Recommendations

Overview

Requirements

Installation

Environment Variables

Build & Run

MCP Client Configuration

Claude CLI (`.mcp.json`)

OpenClaw

Other MCP Clients

Tool Catalog

⚡ Lightning

🌪️ Thunderstorm

🌧️ Precipitation

🌤️ Forecast

👤 Auth & User

🏢 Account

📍 Point Alarms

🗺️ Geo Alarms

📅 Forecast Alarms

Architecture

Authentication & Security

Automatic Auth Flow

HTTP Request Headers

HMAC-SHA256 Signature

Security Recommendations