# Campspot MCP

**First MCP server for the [Campspot](https://software.campspot.com) Online Booking API.** Talk to your campground's reservations, sites, and rate plans from Claude, Cursor, or any MCP client.

## Who is this for?

Campspot is the leading online booking platform for private campgrounds — nearly 2,000 parks and 200,000+ campsites listed on the Campspot Marketplace. Independent campground owners run their day-to-day business in Campspot: setting up sites, adjusting rate plans, watching availability, confirming reservations. This MCP exposes that surface to AI agents so a manager can ask "what's arriving this weekend and what sites are still open for July 4?" and get a real answer instead of a dashboard tour.

## Install

```bash
pip install -e .
```

## Configure

Request a per-park API key from the Campspot support team (activation is a one-time access fee plus the standard partner authentication flow — see https://support.campspot.com/online-booking-api).

```bash
export CAMPSPOT_API_KEY="your-campspot-api-key"
# Optional: override if you are using a sandbox or per-park base URL
# export CAMPSPOT_BASE_URL="https://api.campspot.com"
```

## Use with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "campspot_mcp": {
      "command": "campspot_mcp",
      "env": {
        "CAMPSPOT_API_KEY": "your-campspot-api-key"
      }
    }
  }
}
```

## Use with Claude Code

```bash
claude mcp add campspot_mcp -- campspot_mcp --env CAMPSPOT_API_KEY=your-key
```

## Tools

| Tool | What it does |
| --- | --- |
| `health_check` | Verifies credentials by hitting `/park`. If this fails, all other tools will too. |
| `get_park_info` | Returns metadata about the configured park (name, timezone, contact, address). |
| `list_sites` | Paginated list of campsites at the park. Optional `limit` and `offset`. |
| `get_site` | Single campsite by id (name, type, capacity, rates). |
| `search_availability` | Find sites available across a date range. Optional `site_ids` to scope. |
| `list_reservations` | List reservations filtered by arrival date range and status. |
| `get_reservation` | Single reservation by id. |
| `list_rates` | List rate plans effective during an optional date range. |

## Example session

```
You:    "What's arriving at our park next weekend, and which sites are still open for July 4?"
Claude: *calls list_reservations(start_date="2026-07-04", end_date="2026-07-06") and search_availability(start_date="2026-07-04", end_date="2026-07-07"), summarises the results*

You:    "Pull up reservation 9384."
Claude: *calls get_reservation(9384), shows the guest details*
```

## Engineering

- Shared `httpx.AsyncClient` with connection pooling + transport retries (encode/httpx pattern).
- Typed exception hierarchy (`CampspotAuthError`, `CampspotNotFoundError`, `CampspotRateLimitError`, `CampspotAPIError`, `CampspotConnectionError`) with structured fields (`http_status`, `request_id`, `retry_after`).
- Application-level retry with exponential backoff + full jitter on 429/5xx, honoring `Retry-After`.
- **isError-compliance**: tools raise bare exceptions so FastMCP sets `isError=true` on the wire. AI agents can distinguish failure from data (Blackwell Systems audit, 54 MCPs / 20 bugs).
- JSONL audit log per tool call to stderr (or `CAMPSPOT_AUDIT_LOG` file) — fail-open, secrets redacted, strings truncated to 256 chars.
- py.typed marker (PEP 561). mypy --strict clean. ruff full rule set clean.

## Development

```bash
pip install -e ".[dev]"
pytest                       # 23 tests, no live API required (respx mocks)
ruff check src tests         # lint
mypy src                     # strict type-check
CAMPSPOT_API_KEY=... campspot_mcp
```

## License

MIT.

## See also

- [Model Context Protocol spec](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
- [Other vertical MCPs by sanjibani](https://github.com/sanjibani?q=-mcp)
- [Custom MCP engagements](https://sanjibani.github.io/mcp-services/)