# Roamtime for Claude Desktop

**When will the autumn leaves peak?** This extension gives Claude real foliage
forecasts for Japan, so it can answer *"where should I go on 20 November?"* or
*"is Nikko past peak by 1 December?"* with dates you can book around — not
guesses from last year's photos.

## Install (one click)

1. Download **[roamtime-foliage.mcpb](https://github.com/cinaisv/roamtime-mcpb/raw/main/roamtime-foliage.mcpb)**.
2. Double-click the file, or drag it onto the Claude Desktop window, and click **Install**.
3. Start asking. No account, no key.

Requires Claude Desktop on macOS or Windows. The extension is a thin client:
nothing runs on your machine except a small launcher that connects Claude to
the hosted Roamtime server at `https://api.roamtime.ai/mcp`.

## Try asking

- "Which foliage spots near Kyoto peak on 20 November?"
- "Best koyo in Tohoku the first week of November, reachable by train"
- "I'm in Tokyo 14–18 November — where are the leaves at their best?"
- "Is Tenryū-ji still at peak on 1 December?"

Every answer comes with the spot's forecast best-viewing window (start and
end dates), a confidence in days, the nearest rail station and distance, the
leaf type, and a link to the spot page with photos and a bilingual guide.

## How the forecasts are made

Roamtime runs temperature-driven phenology models on Japan Meteorological
Agency station data, calibrated against 18 years of observed peak reports so
the windows match reality rather than optimism. Forecasts are refreshed as the
season's weather arrives; every response carries its issue date.

Coverage: all eight regions of Japan, October to mid-December.

## Free tier and API key

| | Free tier | With an API key |
|---|---|---|
| Spots | ~70 most-visited (famous destinations and UNESCO World Heritage sites) | All 686, including regional and hidden-gem spots |
| Data | Best-viewing window per spot | Windows, status, daily refreshes |
| Use | Personal | Personal and commercial |
| Setup | Nothing | Paste the key in the extension's settings |

Request a key at <https://roamtime.ai/#api>. Claude Desktop stores it in your
operating-system keychain and sends it only to `api.roamtime.ai`.

## Tools

All tools are read-only. `search` and `fetch` exist for clients that expect that pair (ChatGPT connectors and deep research).

| Tool | What it does |
|---|---|
| `get_coverage` | Forecast year, issue date, season span, regions, prefectures, spot count, and your access tier. |
| `find_peak_spots` | Spots whose forecast window covers a date or date range, optionally near a place (`near: "Kyoto"`, or lat/lon with a radius), region, or prefecture. |
| `search` | Free-text search by spot name, prefecture, region, or month; returns ids. |
| `fetch` | The full forecast document for one spot id. |

## Using Roamtime from other clients

You don't need this bundle outside Claude Desktop — point any MCP client at
`https://api.roamtime.ai/mcp` (streamable HTTP, no auth):

- **Claude Code:** `claude mcp add --transport http roamtime https://api.roamtime.ai/mcp`
- **claude.ai:** Customize → Connectors → Add custom connector → paste the URL
- **ChatGPT:** Settings → Security and login → Developer mode → add MCP server
- **Cursor and others:** `{ "mcpServers": { "roamtime": { "url": "https://api.roamtime.ai/mcp" } } }`

Full setup notes: <https://roamtime.ai/#mcp>.

## Build the bundle yourself

```bash
npm ci
npx @anthropic-ai/mcpb validate manifest.json
npx @anthropic-ai/mcpb pack . roamtime-foliage.mcpb
```

Node 18 or newer. `server/index.js` is the whole launcher; it starts
[mcp-remote](https://github.com/geelen/mcp-remote) against the server URL and
forwards the optional API key as a bearer token.

## Privacy Policy

The extension sends your queries — dates, place names or coordinates, and the
optional API key you configure — to the Roamtime server at `api.roamtime.ai`
and returns the forecast. It stores nothing on your machine beyond the API
key, which Claude Desktop keeps in the operating-system keychain. No
conversation content other than the tool call itself leaves Claude.

Roamtime's privacy policy — what the server collects, how it is used and
stored, third-party sharing, retention, and contact details — is at
<https://roamtime.ai/privacy>. Terms of service: <https://roamtime.ai/terms>.

## Support

Email <sara.h@roamtime.site>, or open an issue here.

## License

The launcher and packaging in this repository are MIT licensed (see
[LICENSE](LICENSE)). The forecast data Roamtime serves is **not** covered by
that license: all rights reserved by Roamtime.ai, and use beyond the free
tier requires an API key. See <https://roamtime.ai/terms>.