sauna-mcp-server
by divelux
README.md
# sauna-mcp-server
A small [Model Context Protocol](https://modelcontextprotocol.io) server that gives an AI assistant four sauna tools: plan a session, size a heater, look up a bathing tradition, look up a sauna word.
It runs on your own computer over stdio. Every tool is read-only. Nothing is sent over the network, nothing is written to disk, and no state is kept between calls.
Made by [DIVELUX](https://diveluxsaunahat.com), a small family brand in Irvine, California that makes handmade wool sauna hats.
| Tool | What it does | Where the numbers come from |
| --- | --- | --- |
| `plan_session` | Rounds, minutes per round, breaks, final cool-down and glasses of water for a sauna session | The rules of the [Sauna Session Planner](https://divelux.github.io/sauna-session-planner/) ([sauna-planner-core](https://github.com/divelux/sauna-planner-core)) |
| `size_heater` | Heater size for a room: a kW range for an electric heater, a room volume for a wood-burning stove | Harvia and HUUM published sizing rules, as in the [Sauna Heater Size Calculator](https://divelux.github.io/sauna-heater-calculator/) |
| `lookup_tradition` | 28 bathing traditions (Finnish sauna, banya, hammam, onsen, jjimjilbang, temazcal and more) and 12 kinds of bath headwear | The open dataset Sauna Traditions of the World (CC BY 4.0) |
| `lookup_term` | 145 sauna and bathhouse words in 25 languages, with plain-English meanings | The open Sauna Glossary (CC BY 4.0) |
> **Not medical advice.** `plan_session` returns planning numbers for healthy adults: conservative, widely repeated sauna conventions, not research findings and not targets. Every plan ends with the line "Not medical advice. ... Step out if you feel dizzy, sick or faint. ... talk to your doctor first." The server does not know anyone's health.
>
> **Heater sizes are estimates.** Every `size_heater` answer ends with "Always confirm with the heater manufacturer and a licensed electrician."
## Set it up
You need [Node.js](https://nodejs.org/) 20 or newer.
### Claude Code
```sh
claude mcp add sauna -- npx -y sauna-mcp-server
```
Add `--scope user` before the name to have it in every project, or `--scope project` to share it with your team through `.mcp.json`. Check it with `claude mcp list`, or `/mcp` inside Claude Code.
The same server as a `.mcp.json` entry:
```json
{
"mcpServers": {
"sauna": {
"command": "npx",
"args": ["-y", "sauna-mcp-server"]
}
}
}
```
### Claude Desktop
Open Settings from the Claude menu, go to Developer, and click Edit Config. That opens `claude_desktop_config.json`:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
Add the server (keep any servers already listed), save, then quit Claude Desktop completely and start it again:
```json
{
"mcpServers": {
"sauna": {
"command": "npx",
"args": ["-y", "sauna-mcp-server"]
}
}
}
```
### From a copy of this repository
`npx -y sauna-mcp-server` works once the package is on npm. Until then, or to run your own copy:
```sh
git clone https://github.com/divelux/sauna-mcp-server.git
cd sauna-mcp-server
npm install --omit=dev
```
Then use `node` with the full path to `server.mjs` in place of `npx`:
```sh
claude mcp add sauna -- node /full/path/to/sauna-mcp-server/server.mjs
```
```json
{ "mcpServers": { "sauna": { "command": "node", "args": ["/full/path/to/sauna-mcp-server/server.mjs"] } } }
```
Any other MCP client that starts local stdio servers works the same way: the command is `npx -y sauna-mcp-server`, with no arguments and no environment variables.
## Things to ask
- "Plan a sauna session for me: Finnish sauna at 175 °F, I go a few times a month, and I have 90 minutes."
- "My sauna room is 6 by 5 feet with a 7 foot ceiling and a glass door. What size electric heater do I need?"
- "What is the difference between a Russian banya and a Finnish sauna?"
- "What does löyly mean? And what is the Russian word for the sauna whisk?"
## The tools
### `plan_session`
| Argument | Values | Default |
| --- | --- | --- |
| `type` | `dry`, `loyly`, `banya`, `steam`, `infrared` | `dry` |
| `temp` | thermometer reading in `unit`; readings outside the usual range for the type are moved to the nearest end | a typical temperature for the type |
| `unit` | `f`, `c` | `f` |
| `level` | `new`, `regular`, `seasoned` | `new`, the most cautious |
| `total_minutes` | 15 to 180 | 60 |
| `include_ladder` | `true` to add the heat ladder, an illustration of air temperature from ceiling to floor | `false` |
Called with `{"type": "dry", "temp": 175, "unit": "f", "level": "regular", "total_minutes": 90}` it answers:
```text
Sauna session plan: Finnish, dry at 175 °F, regular bather, 90 minutes available.
0:00 Round 1, 11 min
0:11 Cool-down, 11 min
0:22 Round 2, 11 min
0:33 Cool-down, 11 min
0:44 Round 3, 11 min
0:55 Final cool-down, 10 min
In the heat: 3 rounds of 11 min (33 min in total).
Breaks: 11 min between rounds, then a 10 min final cool-down.
Time used: 65 of 90 min (25 to spare). Spare time is not turned into more heat.
Bench: either bench.
Water: 6 glasses of 8 fl oz (48 fl oz, 1440 ml): 1 before, 2 in the breaks, 3 after.
Not medical advice. These are planning numbers for healthy adults, not targets. Step out if you feel dizzy, sick or faint. If you have a health condition or are not sure the heat is right for you, talk to your doctor first.
```
The structured result holds `plan` (exactly what `plan()` of sauna-planner-core returns), `adjustments` (what the planner changed or assumed, in words), `share_url` (the same plan in the web planner), `disclaimer`, and `ladder` when asked for.
The rules, in short: experience sets a band of minutes per round; a hotter room means a shorter round; nobody gets more than 20 minutes at a stretch in a hot room; breaks are at least as long as the rounds; the plan never runs over the time given and never turns spare time into more heat. They are written out in full, with their one outside source (Harvard Health Publishing), in the [sauna-planner-core README](https://github.com/divelux/sauna-planner-core#the-rules).
### `size_heater`
| Argument | Values | Default |
| --- | --- | --- |
| `unit` | `ft` (decimal feet and square feet) or `m` (meters and square meters) | `ft` |
| `length`, `width`, `height` | inside size of the hot room; in feet use decimals, 6 ft 6 in is `6.5` | required |
| `glass_area` | uninsulated glass: door, window, glass wall | 0 |
| `masonry_area` | uninsulated stone, tile, brick or concrete | 0 |
| `log_walls` | `true` if the inside walls are bare log | `false` |
| `heater` | `electric` or `wood` | `electric` |
Called with `{"length": 6, "width": 5, "height": 7, "glass_area": 12}` it answers:
```text
Electric heater: 5.1 to 7.3 kW for a calculated volume of 257 cu ft (7.3 m³).
High end: the makers' average of 1 kW per cubic meter (Harvia, HUUM). Low end: the 1 kW per 50 cu ft shortcut, which is where Harvia's own worked example lands. Do not go below the low end.
Shop for a heater whose rated room range includes the calculated volume, ideally near the middle.
Room volume: 210 cu ft (5.95 m³). Glass and stone: 12 sq ft, counted as 47 cu ft of extra room (Harvia: 1.2 m³ per m²).
The same room by other published rules: HUUM 249 cu ft (7.1 m³); HUUM North American sheet 269 cu ft (7.6 m³).
Always confirm with the heater manufacturer and a licensed electrician. This is a rule-of-thumb estimate. It cannot see your insulation, vents, climate or wiring. The manual of the heater you buy has the final say on room volume, clearances, breaker and wire size.
```
The structured result is what `calc()` of the calculator returns, plus `confirm` and `sources` (links to the Harvia and HUUM pages each rule comes from). Rooms outside what the calculator covers (a side under 3 ft or over 19 ft 8 in, a ceiling under 5 ft 7 in or over 9 ft 10 in, more glass than the room has surface) come back as a tool error that says which number to check. Every rule and its source is in the [calculator's README](https://github.com/divelux/sauna-heater-calculator#sources). Infrared cabins are sized differently and are not covered.
### `lookup_tradition`
| Argument | Values | Default |
| --- | --- | --- |
| `query` | a name, local name or country: `banya`, `savusauna`, `Japan`, `hamam`. Case, accents and small typos are forgiven | none: lists all 28 |
| `list` | `true` to list the names instead of searching | `false` |
| `limit` | most full records to return, 1 to 10 | 3 |
Each match is the full dataset row (heat source, typical air or water temperature in °F and °C, humidity, typical length of a stay, water on the stones, rituals, cooling, headwear, UNESCO status, notes) with the matching rows of the headwear table attached. The numbers are compiled reference ranges from general published descriptions, not measurements and not recommendations; an empty field means "not stated".
### `lookup_term`
| Argument | Values | Default |
| --- | --- | --- |
| `query` | the word in any script (`löyly`, `веник`, `찜질방`), its transliteration (`venik`), or an English meaning (`whisk`) | none |
| `language` | a language name or ISO code: `Finnish`, `fi`, `ru` | all 25 |
| `category` | `place`, `room`, `heat source`, `steam`, `tool`, `practice`, `person`, `headwear`, `cooling`, `expression`, `food and drink` | all |
| `limit` | most terms to return, 1 to 25 | 8 |
With no query it lists the terms of the language or category given, or, with nothing at all, the languages and categories. The glossary is a reference word list, not a complete dictionary.
## How results are returned
Each successful call returns `structuredContent` (matching the tool's `outputSchema`) and two text blocks: a plain-English answer, then the same structured data as JSON for clients that only read text. Arguments that do not fit the schema, and rooms the calculator refuses, come back as a tool result with `isError: true` and a message the model can act on. An unknown tool name is a protocol error.
## Protocol
The server is built on the official TypeScript SDK, [`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server) 2.x, and speaks both generations of MCP over stdio:
- the current revision, [2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28): stateless requests that carry their protocol version in `_meta`, and `server/discover`;
- the earlier revisions that open with an `initialize` handshake (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05).
Which one is used is decided by how the client opens the connection. Standard output carries protocol messages only.
## Tests
```sh
npm install
npm test
```
- `test/logic.test.mjs` calls the tool logic directly: the vendored rules and data are the unchanged originals (SHA-256), the planner still gives the golden hash of sauna-planner-core over 42,534 plans, `plan_session` and `size_heater` return exactly what the original functions return, the makers' worked examples come out right, and the searches find what they should.
- `test/stdio-raw.test.mjs` starts the server as a child process and talks to it in raw JSON-RPC with no SDK on the client side, once in the 2026-07-28 style and once per older protocol version: discovery or handshake, `tools/list`, 22 valid and failing tool calls compared with direct calls of the logic, 8 calls the input schema must refuse, an unknown tool, a missing `_meta`, an unsupported version, a clean exit when stdin closes, and nothing but protocol messages on stdout.
- `test/sdk-clients.test.mjs` runs the same calls through the official clients: `@modelcontextprotocol/client` 2.x (automatic negotiation, pinned to 2026-07-28, and legacy mode) and `@modelcontextprotocol/sdk` 1.x. They are dev dependencies; without them these tests are skipped.
## Files
| File | What it is |
| --- | --- |
| `server.mjs` | The MCP server: tool names, descriptions, schemas, stdio |
| `lib/tools.mjs` | The tool logic as plain functions, and the search |
| `vendor/` | Unchanged copies of the planner and heater rules, with checksums |
| `data/` | Copies of the two datasets (CC BY 4.0) |
| `test/` | Tests (not in the npm package) |
## Related
- [Sauna Session Planner](https://divelux.github.io/sauna-session-planner/) and [Sauna Heater Size Calculator](https://divelux.github.io/sauna-heater-calculator/): the same rules as web pages
- [sauna-planner-core](https://github.com/divelux/sauna-planner-core): the planner as a JavaScript package
## Credit and license
Made by [DIVELUX](https://diveluxsaunahat.com), handmade wool sauna hats. More free sauna tools: <https://diveluxsaunahat.com/pages/sauna-tools>
Code: MIT License, © 2026 DIVELUX Inc. See [LICENSE](LICENSE). The data in `data/` is CC BY 4.0, © 2026 DIVELUX; see [data/README.md](data/README.md).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues