Plan US National Park Service trips — find parks, check alerts and closures, find campgrounds, browse things to do and events via the NPS Data API. STDIO or Streamable HTTP.\n
\n\n[](https://github.com/cyanheads/national-parks-mcp-server/releases/latest/download/national-parks-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=national-parks-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbmF0aW9uYWwtcGFya3MtbWNwLXNlcnZlciJdLCJlbnYiOnsiTlBTX0FQSV9LRVkiOiJ5b3VyLWFwaS1rZXkifX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22national-parks-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fnational-parks-mcp-server%22%5D%2C%22env%22%3A%7B%22NPS_API_KEY%22%3A%22your-api-key%22%7D%7D)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\nSix tools shaped around the trip-planning workflow — resolve a park, then key the detail tools on its code:\n\n| Tool | Description |\n|:---|:---|\n| `nps_find_parks` | Resolve a place name, US state, or free-text query to parks — the required first step. Returns each park's `parkCode` plus a trip-planning summary. |\n| `nps_get_park` | Full detail for up to ten parks in one batched call: description, activities, fees & passes, hours, contacts, directions, weather overview, images. |\n| `nps_get_alerts` | Current alerts for a park or state — closures, hazards, caution, information — with category and recency surfaced first. |\n| `nps_find_campgrounds` | Campgrounds at a park or state: amenities, reservable vs. first-come site counts, reservation info, accessibility, and fees. |\n| `nps_get_activities` | Curated things to do and points of interest: title, duration, location, accessibility, and fee/pet/reservation flags. |\n| `nps_find_events` | Scheduled events within a date range: dates/times, location, category, fee, and registration links. |\n\nCoverage is **US National Park Service sites only** — national parks, monuments, historic sites, seashores — not state parks and not Forest Service or BLM land.\n\n### The `parkCode` spine\n\n`parkCode` (e.g. `yose`, `grca`, `zion`) is the join key for the whole API. The workflow is two steps:\n\n1. **`nps_find_parks`** resolves a name / state / query → `parkCode`(s) plus a summary.\n2. **`nps_get_park`**, **`nps_get_alerts`**, **`nps_find_campgrounds`**, **`nps_get_activities`**, **`nps_find_events`** key on that `parkCode`.\n\n`nps_get_alerts`, `nps_find_campgrounds`, and `nps_find_events` also accept a `stateCode` for statewide queries without a code (e.g. \"is anything closed in Montana's parks?\"). The coordinates returned by `nps_find_parks` / `nps_get_park` feed weather servers (`nws-weather`, `open-meteo`) for a forecast.\n\n---\n\n### `nps_find_parks`\n\nResolve a place name, US state, or free-text query into NPS parks — the entry point.\n\n- Free-text search across park names and descriptions (e.g. `\"yosemite\"`, `\"civil war\"`, `\"redwood\"`); results are re-ranked locally so an exact `parkCode` or name match leads, since NPS returns matches in alphabetical-by-code order with no relevance ranking\n- Filter by two-letter `stateCode` or a comma-separated list (e.g. `\"CA\"`, `\"WY,MT,ID\"`)\n- Optional `activity` filter — case-insensitive substring match applied locally (the API has no activity param) across every site matching `query`/`stateCode`, then paginated\n- Pagination via `limit` (1–50, default 10) and `start` offset; `totalCount` counts the whole matched set, so truncation guidance names the next `start`\n- Summary carries `parkCode`, designation, states, description, coordinates, headline activities, lowest entrance fee, and the NPS page\n- Enrichment reports `totalCount`, applied-filter echo, and broadening guidance when nothing matched\n\n---\n\n### `nps_get_park`\n\nFull trip-planning detail for one or more parks by `parkCode`.\n\n- Batch up to **10 codes in a single upstream call**\n- Always-present core: name, designation, states, description, coordinates, weather overview, NPS page\n- Optional `fields` selector (`activities`, `topics`, `fees`, `hours`, `contacts`, `directions`, `images`) trims the payload to the sections you need\n- Entrance fees and passes broken out by category; operating hours by area/season with per-weekday values; phone and email contacts; representative images (capped at 5, with `imagesTruncated` disclosing when the park has more upstream)\n- Unresolved codes surface as `missingCodes` enrichment with a correction hint; only a fully-empty result is an error\n\n---\n\n### `nps_get_alerts`\n\nCurrent alerts for a park or a whole state, with category and recency leading.\n\n- Filter by `parkCode`, `stateCode`, or free-text `query`; optional `category` (`Danger`, `Caution`, `Information`, `Park Closure`) applied locally (the API has no category param) across every matching alert, then paginated\n- Pagination via `limit` (1–50, default 20) and `start` offset; truncation guidance names the next `start`\n- Sorted most-recent-first, identically on both client surfaces (`structuredContent` and `content[]`)\n- `categoryBreakdown` enrichment counts returned alerts per category — severity-ordered — so severity is legible without scanning each one\n- An empty result is explicitly framed in the notice — good news (the park reports nothing closed or hazardous) when nothing matched, or a paging artifact when `start` ran past the end — never a bare error\n- `lastIndexedDate` is the recency signal — a stale date may mean the condition has changed\n\n---\n\n### `nps_find_campgrounds`\n\nCampgrounds at a park or across a state, flattened to what a camper filters on.\n\n- Filter by `parkCode`, `stateCode`, or free-text `query`; `limit` (1–50, default 15) and `start` pagination\n- Amenity booleans: potable water, showers, RV dump station, toilets, trash collection, RV access — normalized from NPS's mixed array/string amenity fields\n- Reservable vs. first-come-first-served site counts, total sites, reservation guidance and booking URL (often recreation.gov)\n- Lowest fee, accessibility summary, coordinates, and the campground's NPS page\n- Some parks list lodging or backcountry permits instead of NPS-managed campgrounds; an empty result is not an error\n\n---\n\n### `nps_get_activities`\n\nCurated things to do and points of interest, backed by the NPS `/thingstodo` list (distinct from a park's raw activity tags).\n\n- Accepts a **single** 4-letter `parkCode` or a **single** two-letter `stateCode` — at least one is required\n- Free-text `query`; `limit` (1–50, default 15) and `start` pagination\n- Per activity: title, short description, time commitment, location, coordinates, accessibility, season, and the NPS page\n- Reservation-required and pets-permitted booleans; fee description (absence does not guarantee free)\n- Not every park has a curated list; an empty result is not an error\n\n---\n\n### `nps_find_events`\n\nScheduled events at a park within a date range — ranger programs, festivals, tours, interpretive events.\n\n- Filter by `parkCode`, `stateCode`, or free-text `query`; bound the window with `dateStart` / `dateEnd` (`YYYY-MM-DD`)\n- **Page-based pagination** (`pageNumber` / `pageSize`), not offset — the `/events` endpoint differs from the rest of the API\n- Per event: title, date range, time slots, location, category, fee info, and registration / info URLs (HTML stripped to plain text)\n- The events feed is sparser and less consistent than alerts or campgrounds; many parks list few or no events\n- A non-empty upstream `errors[]` array folds into the result notice as a warning rather than failing the request\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):\n\n- Declarative tool definitions — single file per tool, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports — same codebase runs locally or on Cloudflare Workers\n\nNPS-specific:\n\n- One service wrapping the NPS Data API (`developer.nps.gov/api/v1`, `X-Api-Key` auth) across six trip-planning endpoints\n- Aggressive normalization of NPS's inconsistent payloads — numeric and boolean fields returned as strings, nested values (`campsites.totalSites`), array-typed amenity fields, and the distinct `/events` envelope with lowercased field names — coerced to clean domain types before they reach handlers\n- `nps_get_park` batches up to ten park codes into a single upstream request\n- Light retry on transient upstream failures (5xx / network); a missing or invalid key fails loud and names `NPS_API_KEY`\n\nAgent-friendly output:\n\n- Result-set context on every response — `totalCount`, truncation (`shown` / `cap`), applied-filter echo, and empty-result notices reach both the structured and text surfaces\n- The `parkCode`-first workflow is encoded in every tool description; `nps_get_park` returns `missingCodes` so a wrong code self-corrects\n- Uncertainty preserved, never fabricated — every derived field is nullable and a missing upstream value yields `null`, not a guess; coordinates are never invented for downstream weather lookups\n\n## Getting started\n\n### Public Hosted Instance\n\nA public instance is available at `https://national-parks.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP, with this client config:\n\n```json\n{\n \"mcpServers\": {\n \"national-parks-mcp-server\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://national-parks.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-hosted\n\nAdd the following to your MCP client configuration file. A free NPS Data API key is required — [instant signup here](https://www.nps.gov/subjects/developer/get-started.htm).\n\n```json\n{\n \"mcpServers\": {\n \"national-parks-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/national-parks-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"NPS_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"national-parks-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/national-parks-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"NPS_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"national-parks-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"-e\", \"NPS_API_KEY=your-api-key\",\n \"ghcr.io/cyanheads/national-parks-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NPS_API_KEY=... bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3](https://bun.sh/) or higher (or Node.js v24+).\n- A free NPS Data API key — [instant signup](https://www.nps.gov/subjects/developer/get-started.htm). The server fails to start without it.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/national-parks-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd national-parks-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env and set NPS_API_KEY\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas. Key environment variables:\n\n| Variable | Description | Default |\n|:---|:---|:---|\n| `NPS_API_KEY` | **Required.** NPS Data API key, sent as the `X-Api-Key` header. The server fails to start without it. | — |\n| `NPS_BASE_URL` | NPS Data API base URL override (testing / proxy). | `https://developer.nps.gov/api/v1` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |\n| `MCP_HTTP_ENDPOINT_PATH` | Path where the MCP server is mounted. | `/mcp` |\n| `MCP_SESSION_MODE` | Session handling: `auto`, `stateful`, or `stateless`. The schema default `auto` resolves to stateful; this server sets `stateless` explicitly. MCP 2026-07-28 is sessionless in either mode. | `stateless` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t national-parks-mcp-server .\ndocker run --rm -e NPS_API_KEY=your-key -p 3010:3010 national-parks-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/national-parks-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.\n\n## Project structure\n\n| Directory | Purpose |\n|:---|:---|\n| `src/index.ts` | `createApp()` entry point — registers the six tools and inits the NPS service. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |\n| `src/services/nps` | NPS Data API service — HTTP client, retry boundary, error-envelope detection, and all upstream normalization. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`AGENTS.md`](./AGENTS.md) / [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools in the `createApp()` arrays\n- Wrap the external API: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n\n## Data & attribution\n\nData is retrieved from the [NPS Data API](https://developer.nps.gov/) operated by the U.S. National Park Service. Content produced by NPS employees in their official capacity is a U.S. Government work in the public domain (17 U.S.C. §§ 101 and 105). No claim to original U.S. Government works.\n\nNot all content returned by the API is government-authored. Some images and materials carry third-party copyright or other restrictions — check individual item rights before reuse.\n\nThe NPS Arrowhead symbol is a restricted mark protected under 18 U.S.C. § 701. It must not be reproduced or reused without written permission from the NPS Director.\n",
"bytes": 17392,
"sha": "1cb04b4150e6402c0262a913771d6a28fbd97767c0858f5e071c89fb2fa99909",
"repo_slug": "cyanheads/national-parks-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_national_parks_mcp_s_3cdc3902/readme"
}