national-parks-mcp-server

---

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:

• 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. It serves Streamable HTTP; each client takes its own config shape.

For Claude Code:

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

For Cline (cline_mcp_settings.json):

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

For Cursor (mcp.json):

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

Claude Desktop adds remote servers under Settings → Connectors.

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

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