Skip to main content
Glama
National Parks MCP Server

National Parks MCP Server

by cyanheads

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

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


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.

Related MCP server: National Parks MCP Server

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 result includes the park code, designation, states, description, coordinates, activities, NPS page, and the amount and title of the first entrance fee NPS lists. Exact code or name matches rank first. 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

  • Core fields include name, designation, states, description, coordinates, weather overview, and NPS page. Optional sections include fees and passes by category, weekly hours with dated exceptions for each area, contacts, and up to five images (imagesTruncated when more exist).

  • 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

  • Each campground lists weekly and seasonal hours, amenities, reservable and first-come sites, site types, electrical-hookup counts, RV and trailer length limits, and its first-listed fee and title. Reservation guidance and the booking link cover the next step.


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

  • Each activity includes its location, season, duration, accessibility, fees, pet rules, and reservation or permit instructions. A shared activity carries the queried park code when NPS lists that park.


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

  • Each event reports scheduled and cancelled dates within the window, series dates, time slots, location, category, fees, and registration instructions and links. A registration requirement can be present even when NPS supplies no URL.

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

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.

skills/

Published visit-planning guidance for agents using the tools, also served over MCP.

framework-skills/

Development guidance synced from the framework.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers