parksapi-mcp

Generic MCP server over @themeparks/parksapi — every destination the library supports (80+ theme parks worldwide) with no per-park code, plus the 8 Orlando parks the library can't serve without app credentials, via the public api.themeparks.wiki APIs (see src/hosted.ts).

Tools

All tools return JSON as text. entityType filters e.g. ATTRACTION, SHOW, RESTAURANT (case-insensitive). entityId matches entry.id or entry.entityId. limit caps returned items (default 50 when omitted; via MCP it must be a positive int — direct withLimit(arr, 0) also means "all"). category in list_destinations is case-insensitive (disney == Disney). Unknown destinations return a tool result with isError: true (plain message, no protocol error). All tools are read-only (annotations.readOnlyHint: true).

Related MCP server: National Parks MCP Server

Requirements

Node 22+.

Cache

The vendored upstream library keeps a SQLite cache at ./cache.sqlite (plus -shm/-wal) in the server's working directory — override with CACHE_DB_PATH (e.g. CACHE_DB_PATH="$TMPDIR/parksapi-cache.sqlite"). The files are git-ignored; wipe them with:

npm run clean

The hosted Orlando parks also keep a small in-memory TTL cache (60s for wait times/live, 12h for calendars) capped at 100 entries with LRU eviction.

Run

npm run setup:upstream   # once per clone: install + build vendored lib
npm install
npm run build
npm start                # stdio MCP server

Claude Desktop / Hermes config:

{
  "mcpServers": {
    "parksapi": {
      "command": "node",
      "args": ["/path/to/parksapi-mcp/dist/index.js"],
      "env": { "EFTELING_APIKEY": "..." }
    }
  }
}

Orlando parks (no credentials needed)

The TS library leaves Walt Disney World out of scope (Disney locked down the direct facility-service API) and covers Universal Orlando only with app-extracted API keys (without them universalorlando fails with Invalid URL). This server fills the gap with 8 native destinations (same get_entities / get_live_data / get_schedules interface, no credentials):

7 parks read https://api.themeparks.wiki/preview/parks/<ParkAPIID>/{waittime,calendar} (the HostedPark pattern from the legacy JS library). Epic Universe has no ParkAPIID in the preview feed (404), so it reads the v1 live API (universalresort_orlando/live filtered by Epic parkId) plus the v1 schedule endpoint.

Hosted get_schedules is park-level only: one entry keyed by the park entity (<destination>park, e.g. waltdisneyworldmagickingdompark). Filtering by an attraction id yields no rows — filter by the park id or omit entityId.

To add more hosted parks (e.g. Disneyland California), add one entry to HOSTED_DESTINATIONS in src/hosted.ts.

Credentials

Most library-backed destinations need upstream API credentials as env vars (see the parksapi docs). Public ones such as efteling and all 8 Orlando hosted parks work with no credentials.

Tests (vitest, 37 tests)

npm test   # build + full suite

• tests/service.test.ts — registry/helpers (offline)

• tests/hosted.test.ts — WDW + Universal mapping, Epic v1 fallback, registry (offline, stubbed fetch)

• tests/live.test.ts — Efteling live (no credentials)

• tests/protocol.test.ts — real server over JSON-RPC stdio

Examples

• list_destinations → browse ids (efteling, waltdisneyworldmagickingdom, universalepicuniverse…)

• get_live_data {destination: "waltdisneyworldmagickingdom"} → Magic Kingdom wait times

• get_live_data {destination: "universalepicuniverse"} → Epic Universe wait times (v1-backed)

• get_schedules {destination: "efteling"} → operating hours

Upstream

upstream/ is a snapshot of ThemeParks/parksapi (2460a5e). Refresh it with:

rm -rf upstream && git clone --depth 1 https://github.com/ThemeParks/parksapi.git upstream && rm -rf upstream/.git && npm run setup:upstream