National Parks MCP Server
by cyanheads
README.md
<div align="center">
<h1>@cyanheads/national-parks-mcp-server</h1>
<p><b>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.</b>
<div>6 Tools • 1 Skill</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/national-parks-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/national-parks-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](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)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
<div align="center">
**Public Hosted Server:** [https://national-parks.caseyjhand.com/mcp](https://national-parks.caseyjhand.com/mcp)
</div>
---
## Overview
Plan a National Park Service trip: find a park, check alerts and closures, and browse campgrounds, activities, and events. Covers national parks, monuments, historic sites, and seashores, not state parks, Forest Service, or BLM land.
### Tools
| Tool | Description |
|:---|:---|
| `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. |
| `nps_get_park` | Full detail for up to ten parks in one batched call: description, activities, fees & passes, hours, contacts, directions, weather overview, images. |
| `nps_get_alerts` | Current alerts for a park or state — closures, hazards, caution, information — with category and recency surfaced first. |
| `nps_find_campgrounds` | Campgrounds at a park or state: amenities, reservable vs. first-come site counts, reservation info, accessibility, and fees. |
| `nps_get_activities` | Curated things to do and points of interest: title, duration, location, accessibility, and fee/pet/reservation flags. |
| `nps_find_events` | Scheduled events within a date range: dates/times, location, category, fee, and registration links. |
## Capability reference
### `nps_find_parks` <sub>tool</sub>
- Free-text `query`, two-letter `stateCode` (or a comma-separated list such as `"WY,MT,ID"`), and an optional `activity` filter; `limit` 1–50 (default 10) with a `start` offset
- Each result includes the park code, designation, states, description, coordinates, activities, NPS page, and the amount and title of the first entrance fee NPS lists. Exact code or name matches rank first. `totalCount` counts every match.
---
### `nps_get_park` <sub>tool</sub>
- Up to **10** `parkCode`s per call; the optional `fields` selector (`activities`, `topics`, `fees`, `hours`, `contacts`, `directions`, `images`) trims the payload to the sections you need
- Core fields include name, designation, states, description, coordinates, weather overview, and NPS page. Optional sections include fees and passes by category, weekly hours with dated exceptions for each area, contacts, and up to five images (`imagesTruncated` when more exist).
- Codes that match no site come back as `missingCodes`; the call fails (`no_parks_found`) only when none resolve
---
### `nps_get_alerts` <sub>tool</sub>
- Filter by `parkCode`, `stateCode`, free-text `query`, and `category` (`Danger`, `Caution`, `Information`, `Park Closure`); `limit` 1–50 (default 20) with a `start` offset
- Most-recent-first, each alert with its category, `lastIndexedDate` recency, and detail; `categoryBreakdown` counts the returned alerts by severity
- The notice tells an all-clear (no alerts at that location) apart from a filter that matched nothing and a page past the end
---
### `nps_find_campgrounds` <sub>tool</sub>
- Filter by `parkCode`, `stateCode`, or free-text `query`; `limit` 1–50 (default 15) with a `start` offset
- Each campground lists weekly and seasonal hours, amenities, reservable and first-come sites, site types, electrical-hookup counts, RV and trailer length limits, and its first-listed fee and title. Reservation guidance and the booking link cover the next step.
---
### `nps_get_activities` <sub>tool</sub>
- A **single** `parkCode` or a **single** `stateCode` is required, plus an optional `query`; `limit` 1–50 (default 15) with a `start` offset
- Each activity includes its location, season, duration, accessibility, fees, pet rules, and reservation or permit instructions. A shared activity carries the queried park code when NPS lists that park.
---
### `nps_find_events` <sub>tool</sub>
- Filter by `parkCode`, `stateCode`, or `query` within a `dateStart` / `dateEnd` window (`YYYY-MM-DD`); pages by `pageNumber` and `pageSize` (1–50, default 15), not by offset
- Each event reports scheduled and cancelled dates within the window, series dates, time slots, location, category, fees, and registration instructions and links. A registration requirement can be present even when NPS supplies no URL.
- Errors NPS reports alongside results fold into the notice instead of failing the call
## Features
Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
NPS-specific:
- One service wrapping the NPS Data API (`developer.nps.gov/api/v1`, `X-Api-Key` auth) across six trip-planning endpoints
- 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
- `nps_get_park` batches up to ten park codes into a single upstream request
- Light retry on transient upstream failures (5xx / network); a missing or invalid key fails loud and names `NPS_API_KEY`
- Coordinates returned by `nps_find_parks` / `nps_get_park` feed weather servers (`nws-weather`, `open-meteo`) for a forecast
Agent-friendly output:
- Visit-planning guidance — the published [`national-parks-guide`](./skills/national-parks-guide/SKILL.md) skill checks park identity, access, reservation evidence, and event dates. It ships with plugins, npm, Docker, and MCPB, and MCP clients discover it through the Skills extension (`skill://national-parks-guide/SKILL.md`).
- Result-set context on every response — `totalCount`, truncation (`truncated` / `shown` / `cap`), applied-filter echo, and empty-result notices reach both the structured and text surfaces
- Many parks list no campgrounds, curated activities, or events; an empty result comes back with a notice on where else to look, never as an error
- The `parkCode`-first workflow is encoded in every tool description; `nps_get_park` returns `missingCodes` so a wrong code self-corrects
- Uncertainty preserved, never fabricated — missing coordinates, directions, fees, and amenity values come back `null`, not a guess; coordinates are never invented for downstream weather lookups
## Getting started
Connect to the hosted instance, no install:
```sh
claude mcp add --transport http national-parks-mcp-server https://national-parks.caseyjhand.com/mcp
```
Or run it locally:
```sh
claude mcp add national-parks-mcp-server -e NPS_API_KEY=your-key -- npx -y @cyanheads/national-parks-mcp-server
```
For other clients, add this to the MCP config file:
```json
{
"mcpServers": {
"national-parks-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/national-parks-mcp-server"],
"env": {
"NPS_API_KEY": "your-api-key"
}
}
}
}
```
Get a free [NPS Data API key](https://www.nps.gov/subjects/developer/get-started.htm). For Docker or a source build, see [Running the server](#running-the-server).
## Configuration
All configuration is validated at startup via Zod schemas. Key environment variables:
| Variable | Description | Default |
|:---|:---|:---|
| `NPS_API_KEY` | **Required.** NPS Data API key, sent as the `X-Api-Key` header. The server fails to start without it. | — |
| `NPS_BASE_URL` | NPS Data API base URL override (testing / proxy). | `https://developer.nps.gov/api/v1` |
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |
| `MCP_HTTP_ENDPOINT_PATH` | Path where the MCP server is mounted. | `/mcp` |
| `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` |
| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
| `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
| `LOG_TOOL_FAILURE_PAYLOADS` | Log each failed tool call's arguments and result, redacted by key name and capped at `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES` (default `16384`). A secret inside a free-form value is not redacted. | `false` |
| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |
See [`.env.example`](./.env.example) for the full list of optional overrides.
## Running the server
### Local development
Requires [Bun v1.4.4](https://bun.sh/) or higher (or Node.js v24+) and an NPS Data API key.
- **Clone and install:**
```sh
git clone https://github.com/cyanheads/national-parks-mcp-server.git
cd national-parks-mcp-server && bun install
cp .env.example .env # set NPS_API_KEY
```
- **Build and run:**
```sh
# One-time build
bun run rebuild
# Run the built server
bun run start:stdio
# or
bun run start:http
```
- **Run checks and tests:**
```sh
bun run devcheck # Lint, format, typecheck, security
bun run test # Vitest test suite
bun run lint:mcp # Validate MCP definitions against spec
```
### Docker
```sh
docker run --rm -e NPS_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/national-parks-mcp-server:latest
```
The image defaults to HTTP transport, stateless session mode, and logs to `/var/log/national-parks-mcp-server`. To run over stdio, use `docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio -e NPS_API_KEY=your-key ghcr.io/cyanheads/national-parks-mcp-server:latest`. Build locally with `docker build -t national-parks-mcp-server .`; OpenTelemetry peers are installed by default — add `--build-arg OTEL_ENABLED=false` to omit them.
## Project structure
| Directory | Purpose |
|:---|:---|
| `src/index.ts` | `createApp()` entry point — registers the six tools and inits the NPS service. |
| `src/config` | Server-specific environment variable parsing and validation with Zod. |
| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |
| `src/services/nps` | NPS Data API service — HTTP client, retry boundary, error-envelope detection, and all upstream normalization. |
| `skills/` | Published visit-planning guidance for agents using the tools, also served over MCP. |
| `framework-skills/` | Development guidance synced from the framework. |
| `tests/` | Unit and integration tests mirroring `src/`. |
## Development guide
See [`AGENTS.md`](./AGENTS.md) / [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no `try/catch` in tool logic
- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage
- Register new tools in the `createApp()` arrays
- Wrap the external API: validate raw → normalize to domain type → return output schema; never fabricate missing fields
## Data & attribution
Data 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.
Not 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.
The 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.
## Contributing
Issues are welcome. Run checks and tests before submitting:
```sh
bun run devcheck
bun run test
```
## License
Apache-2.0 — see [LICENSE](LICENSE) for details.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues