Pitchup.com MCP server

An MCP server that lets Claude, ChatGPT and other MCP clients work with a campsite's Pitchup.com supplier account: campsites, pitch types, pitches, charge types, prices and stay rules, allocation, extras and bookings, and (when enabled) setting allocation, prices and charge types. It is built from Pitchup's public API Integration Guide, which is published as one OpenAPI 3.0.3 document (docs.pitchup.com/api/pitchup-api-openapi.yaml, 24 operations, 14 schemas, with the whole guide in its description).

Once it's connected, a site owner or manager can ask things like:

• "Who's arriving on Saturday, how many people and dogs, and does anyone have special requests?"

• "What bookings came in or changed since yesterday morning?"

• "What's the nightly price for electric pitches in August, and which days are closed to arrivals?"

• "Is there allocation for the bell tent from 14 to 18 July?"

• With writes enabled: "Set max allocation to 3 for electric pitches for all of August, and put weekend prices up to £28."

Tools

Not covered on purpose: every DELETE (charge types, bookings, pitches, webhooks), creating or amending bookings and Reserved bookings, creating pitches and charge types, POST /rest/api/arrival/ (single arrival days; set_pricing covers ranges), PATCH /rest/api/extra/, webhooks, and the currency and language lists.

Related MCP server: Amiqus MCP server

Setup

Requires Node 18 or later.

npm install
npm run build

You need an API key: in the Pitchup Manager Portal, open My details and copy the key from the API key section. Sandbox and Live keys are different, and the sandbox needs its own sign-up at www.sandbox.pitchup.com/supplier2/signup/. The key is sent as Authorization: Token <key>; a key pasted with its Token prefix is accepted and the prefix dropped.

Claude Desktop: add this to claude_desktop_config.json:

{
  "mcpServers": {
    "pitchup": {
      "command": "node",
      "args": ["/absolute/path/to/pitchup-mcp/dist/index.js"],
      "env": { "PITCHUP_API_KEY": "your-sandbox-key", "PITCHUP_ENV": "sandbox" }
    }
  }
}

Claude Code:

claude mcp add pitchup -e PITCHUP_API_KEY=your-sandbox-key -e PITCHUP_ENV=sandbox -- node /absolute/path/to/pitchup-mcp/dist/index.js

Safety defaults

• Read-only unless PITCHUP_ALLOW_WRITES=true. Read tools carry the MCP readOnlyHint annotation. The four write tools are marked destructiveHint: true (each overwrites existing allocation days, prices or charge type fields; setting allocation to 0 stops sales on those dates) and idempotentHint: true. Nothing is ever deleted: the server has no tool that sends DELETE or PATCH, and the test suite asserts that no such request is made.

• Sandbox by default. PITCHUP_ENV=live has to be set on purpose.

• Guests: the lead guest's name, party size, dates, pitch, unit, extras, special requests and amounts are returned by default. The booking's structured contact fields (email, telephone, postal address with street, city, county, postcode and country, names_of_all_party_members, car_registration_number and child_ages) are only returned when a tool is called with include_contact_details=true.

• Free text is not withheld, only redacted, and the redaction is a heuristic. A campsite can require guests to write their vehicle registration and the names of everyone in the party in the special requests field (the pitch type's require_car_registration and require_party_names, which the spec describes as "included in the special requests field"), and guests can type anything else there. By default, in special requests, the unit description, group name and cancellation reason: email addresses become [email redacted]; phone-number-like sequences become [phone redacted] (international numbers written with + or 00, including +44 (0)7700 …, UK numbers with a bracketed area code, UK-style numbers starting with 0, and 10-digit numbers starting with 7, a UK mobile without its 0; other such digit strings may be redacted too, while IDs, dates and amounts are left alone); upper-case UK postcodes become [postcode redacted]; and current-format UK registrations (AB12 CDE) become [registration redacted]. Names (such as the party names a campsite asks for), street addresses, lower-case postcodes, older or foreign registration formats and dates of birth written in free text are returned as typed. The test suite checks this with a booking on a pitch type that requires both.

• Payment data is never returned, even on request: the card type and number, charge_id, token_id, stripe_charge_id and the data field of a booking, and the campsite's payment_email, stripe_token, card_types and payment timings. Only the payment status word (pending, paid …) and its due date are passed on. A card number a guest types into free text (13 to 19 digits starting with 1 to 9, grouped or not) is replaced with [card number redacted] in every case, with or without include_contact_details; this is a pattern match, so a card number written in some other way (split by words, say) would not be caught.

• The campsite's own email, the manager's email, its phone numbers and postal address are only returned with include_contact_details; its notices, useful info and cancellation policy have emails, phone numbers, UK postcodes and UK registrations redacted by default, as above.

• Pitch calendar links are only returned with include_contact_details: the guide describes the Pitchup feed (pitchup_calendar_feed) as a signed link whose events carry the customer's name, telephone, email and address, and external feed links often carry their own tokens. By default a pitch shows how many external feeds it has and their sync status. Nothing is ever downloaded.

• Input is checked before any call: pitch type, pitch and charge type IDs must be positive whole numbers (the spec types them as numbers), campsite slugs letters, digits, _ and -, dates real YYYY-MM-DD dates, booking creation and modification filters a date or YYYY-MM-DD HH:MM[:SS] (the guide's datetime example), prices decimal strings such as 10.50. Write tools refuse locally a range that ends before it starts, a repeated date, min_days above max_days, both or neither of allocation and max_allocation, and a pricing request with nothing to change.

• Pagination follows the next link exactly as Pitchup returns it, as the guide asks, with page_size=100 (the documented maximum) on the first request, until next is null or the tool's max_results is reached; an empty page with a next link is followed too. A list cut short says so with complete: false and a note, whether it was cut by Pitchup's paging limit or by max_results after a filter this server applies itself (pitch type, charge type, campsite). A 200 whose JSON is not a list (no results array) is an error, not an empty list. A next link on another host is not followed, so the API key is only ever sent to the configured Pitchup host.

• check_availability reads at most 30 pages of allocation days (7.5 seconds of request spacing plus Pitchup's own response time), to stay within the MCP client's default 60-second request timeout in case Pitchup ignores after/before on allocation days; when it stops early it says so and does not claim that a night it did not find has no allocation day.

• Rate limits: the guide documents none; its best-practice list only says failed requests should be retried "on a reasonable schedule". Requests are spaced 250 ms apart (about four per second, a guess on the polite side). A 429 is retried at most twice for any method, on the assumption that a rate-limited request was not processed, waiting for Retry-After (whole or fractional seconds, or an HTTP-date; 2 s before the second attempt and 4 s before the third when the header is absent). Each wait is capped at 10 seconds; if Pitchup asks for longer, the call gives up at once and says how long to wait.

• 502, 503 and 504 are retried the same way for GET only; after three failures the error says the service may be unavailable, without the gateway's HTML. A write is never retried after a gateway error, because Pitchup may already have queued the job; the error says to check the current values with the matching list tool first.

• A 200 whose body is not JSON (a proxy or login page) is an error described by content type and size, never an empty list. A rejected key produces a message naming PITCHUP_API_KEY, the environment in use and the Sandbox/Live difference. Error messages pass on only JSON fields from Pitchup (at most six), with contact details redacted and the API key scrubbed.

Tests

npm test

The test suite (30 checks, about 195 requests to the mock, about 60 seconds):

1. Validates every fixture record against the schemas in Pitchup's published OpenAPI document with Ajv (strict: false, ajv-formats, plus the spec's decimal format): CampsiteBase; the GET /pitchtype/{pk}/ results item (with all 44 keys it marks required) and PitchTypeBase; the POST /pitch/ response and PitchBase; ChargeTypeBase and the GET /chargetype/{chargetype_id}/ response; the GET /arrival/ results item and ArrivalBase; AllocationBase; ExtraBase; ExtraPriceBase; the POST /booking/ response and BookingBase; and the API root. The spec is downloaded from docs.pitchup.com/api/pitchup-api-openapi.yaml to spec.yaml on the first run. Where a component schema disagrees with the guide's own examples, the disagreeing properties are left out of that one check and the suite proves the list is exact (every error the full schema reports is on a listed property, and every listed property does fail): BookingBase types adults, party, extras, payment_status, price and taxes as strings while the guide's booking example and the POST /booking/ response schema show numbers, objects and arrays (the fixtures follow the example and pass that response schema in full); PitchTypeBase types pitches and lead_price as strings and ground_type as non-nullable, where the GET /pitchtype/{pk}/ schema and example use an array, a number and null; PitchBase types calendar_feeds as a string where the guide and the POST /pitch/ schema use an array.

2. Starts a local mock of the API under /rest/api/ that serves those fixtures with the documented Authorization: Token <key> check and DRF-style pagination (next/previous links, count on page-number lists, a cursor on bookings as in the guide's booking example, page_size honoured up to 100, booking pages capped at 3 by the mock so the suite pages), 401s with the guide's messages for a missing key, a wrong key and "Token" typed twice, 404 Not found. for unknown IDs, 405 for other methods, and injected 429s, 5xx gateway pages, a 400 and an HTML 200. The mock's list, detail and write responses are validated against the spec's response schemas (list envelopes with next/previous allowed to be null, as the guide's "Pagination" section says), the write request examples from the spec are posted to it, and its error bodies are validated against a schema written by hand (test/schemas.mjs), because the spec documents no error response: the messages are the ones the guide's troubleshooting table quotes, and the suite checks each one appears in the spec.

3. Starts the built server and drives it over stdio with the official MCP client: 27 checks covering tools/list and the annotations (14 read tools read-only; 4 write tools destructive and idempotent), every read tool, pagination following next across three pages of 100 arrival days and four cursor pages of bookings to a null next, an empty page with a next link followed, a 200 with non-list JSON reported as an error, the booking filters (the names are read from the guide's "Filtering bookings" section and compared with the tool's inputs, and each of the 20 is passed through exactly: status as its numeric key, pitch as the pitch ID, a datetime with a space sent as %20), a list cut short by max_results saying so (unfiltered, and after this server's own pitch type, charge type and campsite filters in all five tools that have one), a GET /pitchtype/{pk}/ answer holding another pitch type (as a list and as an object) refused by get_pitch_type, get_pricing, check_availability and set_allocation with no request after it, and set_allocation refusing a record whose url points at another pitch type, requests within one tool call spaced at least 240 ms apart, the date/after/before filters on arrival and allocation days, the external_id filter on pitches, the spec's list-shaped GET /pitchtype/{pk}/ answer and a plain object, redaction of guest and campsite contact details and calendar links by default and their return on request (including phone numbers written (01632) 960555, +44 (0)7700 …, 0044 … and 7700900123 in free text), a booking on a pitch type that requires the registration and party names in special requests (registration, postcode, card number and mobile redacted by default, names and street returned as typed, the card number redacted even on request), card and payment fields never returned in either case, list_arrivals filtering and totals (a Confirmed status counted as confirmed, a booking without party.dogs not counted as 0 dogs, and a null dog total when no booking has one), check_availability naming a night without an allocation day and a night with nothing left, refusing 91 nights and accepting 90, stopping after 30 pages of allocation days and then reporting the result as partial, list_extras capping the variable prices at max_results, the write gate with the variable unset and false, every write body validated against the spec's request schema (POST /allocation/ as one object and as a list, POST /pitchtype/{pk}/allocation/ with max_allocation and with allocation, POST .../pricing/ against its request schema and ChargeTypePricingBase, the whole-record PUT /chargetype/{id}/), local refusals before any call (reversed ranges, a repeated date, min_days above max_days, both or neither allocation field, nothing to change, a price that is not a decimal string), bad IDs and dates rejected before any call, the 404 and 401 messages (a 401 sent once, not retried), a 400 passed on redacted, an error body that echoes the key passed on with the key scrubbed and at most six messages, the 429 retry waiting for Retry-After in the whole-seconds, fractional-seconds and HTTP-date forms and 2 s then 4 s when it is absent, giving up after three attempts and at once above the cap, a 429 on a write retried once, a 502 retried for GET and a 503 on a write not retried, a GET failing three times reported without the HTML, a non-JSON 200 reported as an error without quoting it, a next link on another host not followed, a key pasted with Token sent once, and that every request carried Authorization: Token <key>, Accept: application/json; version=2023-08-25 and a documented method and path (the spec's paths plus GET /rest/api/pitchtype/, which the suite checks is written in the guide). One more check reads the environment rules (sandbox default, live, bad values refused) from the built dist/config.js without any network call.

The fixtures avoid null in fields the spec does not mark nullable, although the guide's examples show null in several of them (external_id, arrival_time, cancelled_at, name and notes on pitches, many campsite fields); the server treats null, an empty string and the string "null" the same way.

Status

This is a working prototype. It has not yet been run against the live API or the sandbox, because it was built without a Pitchup account. Everything below is taken from the published guide and should be confirmed on a sandbox account (the sandbox sign-up is self-serve; test bookings need Pitchup to activate the listing):

• The error responses: the status codes and bodies for a missing or wrong key (the mock answers 401 {"detail": "Invalid token."}), for an unknown ID (404 Not found.), for validation errors (the 400 body shape is not documented; the server reads any JSON strings in it) and for rate limiting (no 429 is documented at all).

• The API version: that Accept: application/json; version=2023-08-25 is honoured, and which field names and status values come back under it (the guide's booking example shows "status": "paid", which version 2019-01-21 says became confirmed).

• GET /rest/api/pitchtype/: it is documented in the guide's text and the API root's example, not in the spec's paths. Whether it accepts a campsite filter (the guide says "optionally filtered by campsite" without naming the parameter; this server filters by the campsite link itself).

• GET /rest/api/pitchtype/{pk}/: the spec documents a paginated list as its answer (and whether that list can hold other pitch types is not said); the server takes the record with the requested ID from results, or accepts a plain object with that ID, and treats an answer without that ID as not found.

• Pagination: that page_size up to 100 is honoured on every list, that next links point to the same host the request went to (on the sandbox, the sandbox host; the guide's examples all use www.pitchup.com), which lists use cursors and which page numbers, and whether the API root answers an object (spec schema) or a one-element array (guide example); both are handled.

• Filter semantics: whether after and before on arrival and allocation days compare the date and include it (check_availability asks for one day more on each side and picks the nights itself, so either reading works); whether allocation days accept date, after and before at all (the guide documents them for arrival days and names them in its general filtering section, but its allocation section lists no filters); that booking after/before compare the creation date, as the guide says, whether they include the given time, and that they accept YYYY-MM-DD HH:MM:SS; that status takes the numeric key (the guide's example is status=3) and pitch the pitch ID; that first_name/last_name match "containing" case-insensitively.

• Booking status spelling: the status values list and the 2019-01-21 changelog write confirmed, the booking response table's example value is "Confirmed"; list_arrivals compares case-insensitively, so either works, and shows the status as sent.

• Dogs: the guide lists dogs in party under "What's new in version prerelease", and this server pins 2023-08-25 by default, so the booking API may send no dog count at all. list_arrivals then reports the number of dogs as unknown (null, or a total of the bookings that do carry one, with a note) rather than 0. Whether party.dogs comes back under 2023-08-25 is unconfirmed; PITCHUP_API_VERSION=prerelease should include it.

• Booking field shapes: party, payment_status, extras and taxes as objects and arrays, as in the guide's example and the POST /booking/ schema rather than BookingBase. The shape of an item in extras is not shown anywhere (the example list is empty; the response table names extra, extra price and quantity); the server reads extra or name, quantity and price, extra price or extra_price.

• The schema disagreements listed under Tests (BookingBase, PitchTypeBase, PitchBase), the ExtraBase status enum (active, deleted, disabled) against the guide's example value inactive, and which fields are really nullable.

• Writes, all untested on a real account: that POST /rest/api/allocation/ accepts the pitch type's own url as pitchtype and a JSON list of up to 90 days, and what it answers for a list (the guide's example response is a paginated list; the server accepts a list, a paginated list or one object); that POST /pitchtype/{pk}/allocation/ accepts max_allocation (documented in the guide's text and response table, not in the request schema); that POST .../pricing/ takes is_soft_close and closed_to_departure as JSON booleans and weekdays as integers (the guide's examples quote them as strings, the spec's example quotes weekdays as strings); that the task_id jobs apply as described (a job's result can only be queried in the prerelease version); and that PUT /chargetype/{id}/ accepts name, description, pitchtype and is_active alone, and what it does to status when is_active changes.

• Past dates: the guide says updates to arrival and allocation days in the past are refused, using Europe/London time; the server does not check this itself.

• How many requests per second the API tolerates; nothing is documented, so the 250 ms spacing is a guess.

Going to production

This version runs locally over stdio, with the site owner's own API key. For site owners to connect from claude.ai or ChatGPT without handling keys, the next step is a remote server (Streamable HTTP) behind OAuth, hosted by Pitchup, and then a listing in the Claude and ChatGPT connector directories. A production version, tested on a sandbox site with an activated listing, would also cover the booking amendment and Reserved-booking endpoints, the task_id status check once it leaves prerelease, and webhooks for new bookings and cancellations.

Licence

MIT. Built by Alexandru Dragoș (alexandru.dragos96@gmail.com) with an AI agent (Claude) working under his direction.