national-parks-mcp-server

<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">

</div> <div align="center">

</div> <div align="center">

Public Hosted Server: 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 _tool

• 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 park carries its parkCode plus designation, states, description, coordinates, headline activities, lowest entrance fee, and NPS page; exact parkCode or name matches rank first, and totalCount counts every match

---

nps_get_park _tool

• Up to 10 parkCodes per call; the optional fields selector (activities, topics, fees, hours, contacts, directions, images) trims the payload to the sections you need
• Always returns name, designation, states, description, coordinates, weather overview, and NPS page; fees and passes by category, hours by area and season, contacts, and up to 5 images (imagesTruncated when the park has more)
• Codes that match no site come back as missingCodes; the call fails (no_parks_found) only when none resolve

---

nps_get_alerts _tool

• 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 _tool

• Filter by parkCode, stateCode, or free-text query; limit 1–50 (default 15) with a start offset
• Per campground: amenities (potable water, showers, dump station, toilets, trash collection, RV access) as yes, no, or unknown; reservable, first-come, and total site counts; reservation guidance and booking URL; lowest fee, accessibility, coordinates, and NPS page

---

nps_get_activities _tool

• A single parkCode or a single stateCode is required, plus an optional query; limit 1–50 (default 15) with a start offset
• Per activity: title, short description, time commitment, location, coordinates, accessibility, season, reservation-required and pets-permitted flags, fee description, and NPS page

---

nps_find_events _tool

• 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
• Per event: title, date range, occurrenceDates inside the window (isRecurring marks a series), time slots, location, category, fee, and registration and info URLs
• Errors NPS reports alongside results fold into the notice instead of failing the call

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:

• Visit-planning guidance — the published national-parks-guide 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:

claude mcp add --transport http national-parks-mcp-server https://national-parks.caseyjhand.com/mcp

Or run it locally:

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:

{
  "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. For Docker or a source build, see 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 (spans, metrics, completion logs). | false |

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

Running the server

Local development

Requires Bun v1.4 or higher (or Node.js v24+) and an NPS Data API key.

• Clone and install:

  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:

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