National Parks MCP Server README

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

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:

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:

  shCopy

  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:

  shCopy

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

• Run checks and tests:

  shCopy

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

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.