io.github.cyanheads/national-parks-mcp-server

---

Overview

US National Park Service trip planning over the NPS Data API. Resolve a park to its parkCode, then check alerts and closures, find campgrounds, and browse activities and events — coverage is US NPS sites only (national parks, monuments, historic sites, seashores), not state parks, Forest Service, or BLM land. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

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 _tool

• 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
• Filter by two-letter stateCode or a comma-separated list (e.g. "CA", "WY,MT,ID")
• Optional activity filter — case-insensitive substring match applied locally (the API has no activity param) across every site matching query/stateCode, then paginated
• Pagination via limit (1–50, default 10) and start offset; totalCount counts the whole matched set, with broadening guidance when nothing matches
• Summary carries parkCode, designation, states, description, coordinates, headline activities, lowest entrance fee, and the NPS page

---

nps_get_park _tool

• Batch up to 10 codes in a single upstream call
• Always-present core: name, designation, states, description, coordinates, weather overview, NPS page
• Optional fields selector (activities, topics, fees, hours, contacts, directions, images) trims the payload to the sections you need
• 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)
• Unresolved codes surface as missingCodes enrichment with a correction hint; only a fully-empty result is an error

---

nps_get_alerts _tool

• 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
• Pagination via limit (1–50, default 20) and start offset; truncation guidance names the next start
• Sorted most-recent-first, identically on both client surfaces (structuredContent and content[])
• categoryBreakdown enrichment counts returned alerts per category — severity-ordered — so severity is legible without scanning each one
• 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
• lastIndexedDate is the recency signal — a stale date may mean the condition has changed

---

nps_find_campgrounds _tool

• Filter by parkCode, stateCode, or free-text query; limit (1–50, default 15) and start pagination
• Amenity booleans: potable water, showers, RV dump station, toilets, trash collection, RV access — normalized from NPS's mixed array/string amenity fields
• Reservable vs. first-come-first-served site counts, total sites, reservation guidance and booking URL (often recreation.gov)
• Lowest fee, accessibility summary, coordinates, and the campground's NPS page
• Some parks list lodging or backcountry permits instead of NPS-managed campgrounds; an empty result is not an error

---

nps_get_activities _tool

• Accepts a single 4-letter parkCode or a single two-letter stateCode — at least one is required
• Free-text query; limit (1–50, default 15) and start pagination
• Per activity: title, short description, time commitment, location, coordinates, accessibility, season, and the NPS page
• Reservation-required and pets-permitted booleans; fee description (absence does not guarantee free)
• Not every park has a curated list; an empty result is not an error

---

nps_find_events _tool

• Filter by parkCode, stateCode, or free-text query; bound the window with dateStart / dateEnd (YYYY-MM-DD)
• Page-based pagination (pageNumber / pageSize), not offset — the /events endpoint differs from the rest of the API
• Per event: title, date range, time slots, location, category, fee info, and registration / info URLs (HTML stripped to plain text)
• The events feed is sparser and less consistent than alerts or campgrounds; many parks list few or no events
• A non-empty upstream errors[] array folds into the result notice as a warning rather than failing the request

Features

Built on @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:

• Result-set context on every response — totalCount, truncation (shown / cap), applied-filter echo, and empty-result notices reach both the structured and text surfaces
• 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 — every derived field is nullable and a missing upstream value yields null, not a guess; coordinates are never invented for downstream weather lookups

Getting started

Public Hosted Instance

A 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:

{
  "mcpServers": {
    "national-parks-mcp-server": {
      "type": "streamable-http",
      "url": "https://national-parks.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file. A free NPS Data API key is required — instant signup here.

{
  "mcpServers": {
    "national-parks-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/national-parks-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NPS_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "national-parks-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/national-parks-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NPS_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "national-parks-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "NPS_API_KEY=your-api-key",
        "ghcr.io/cyanheads/national-parks-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NPS_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4 or higher (or Node.js v24+).
• A free NPS Data API key — instant signup. The server fails to start without it.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/national-parks-mcp-server.git

2. Navigate into the directory:

cd national-parks-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env and set NPS_API_KEY

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
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.	in-memory
OTEL_ENABLED	Enable OpenTelemetry instrumentation.	false

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t national-parks-mcp-server .
docker run --rm -e NPS_API_KEY=your-key -p 3010:3010 national-parks-mcp-server

The 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.

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.
tests/	Unit and integration tests mirroring src/.

Development guide

See AGENTS.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 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:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.