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

@cyanheads/national-parks-mcp-server

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.

6 Tools

Public Hosted Server: https://national-parks.caseyjhand.com/mcp

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

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:

• 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

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

1. Navigate into the directory:

cd national-parks-mcp-server

1. Install dependencies:

bun install

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

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

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.