humanitix-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@humanitix-mcp List my upcoming events and show the sales summary for the first one."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
humanitix-mcp
A read-only MCP (Model Context Protocol) server for the Humanitix Public API.
This repository contains the completed Phase 1-5 implementation: a uv
project, an async read-only Humanitix HTTP client, Pydantic response models,
deterministic trimmed formatting helpers, and a stdio MCP server that exposes
nine read-only tools.
Setup
This project uses uv and requires Python 3.11+.
uv sync --extra devCreate a Humanitix Public API key in Account → Advanced → Public API key,
following the official Humanitix Public API
documentation.
Generating a replacement key invalidates the prior key. Copy .env.example to
.env and add the key locally:
cp .env.example .envAt startup, the server loads the project-local .env. Explicitly set
HUMANITIX_API_KEY and HUMANITIX_BASE_URL environment variables take
precedence; HUMANITIX_BASE_URL otherwise defaults to
https://api.humanitix.com. HUMANITIX_DOTENV_PATH is an advanced explicit
dotenv-path override, primarily for test or custom setups. Never put an API
key in MCP configuration, source control, logs, or issue comments.
Related MCP server: hit-mcp
Running the server
The server communicates over stdio and is the MCP transport expected by Claude Desktop and MCP Inspector:
uv run humanitix-mcpWith the MCP Inspector:
npx @modelcontextprotocol/inspector uv run humanitix-mcpThe server creates one HumanitixClient per stdio connection and closes it
when the connection ends.
Claude Desktop configuration
Add this secret-free server entry to Claude Desktop's MCP configuration:
{
"mcpServers": {
"humanitix": {
"command": "uv",
"args": [
"--directory",
"/Users/kevin/Documents/GitHub/humanitix-mcp",
"run",
"humanitix-mcp"
]
}
}
}The credential stays solely in the gitignored project-local .env, never in
the Claude Desktop configuration. The server loads that file when started by
the command above.
Claude Code CLI project configuration
This separate, project-scoped Claude Code CLI .mcp.json configuration uses a
secret-free shell wrapper that, from Claude's project-root working directory,
exports variables from the local .env and then executes uv run humanitix-mcp. It contains no machine-specific paths, so a clone works after
creating its own .env; the key remains only in that untracked local
environment file. Check the Claude Code configuration with:
claude mcp listThe Claude-mediated humanitix_sales_summary verification is not yet
complete: the local Claude CLI returned OAuth 401 before it made an MCP call.
Re-authenticate the local Claude CLI using its normal login flow, confirm
claude mcp list again, then retry the sales-summary call. This is separate
from Humanitix API-key authentication.
Project structure
src/humanitix_mcp/— Python package.server.py— MCP server entry point and tool handlers (Phase 4).client.py— Async Humanitix API HTTP client with auth, retry, and pagination (Phase 2).models.py— Pydantic response models (Phase 3).formatting.py— Deterministic response trimming helpers with a raw-payload opt-in escape hatch (Phase 3).
tests/— Test suite.tests/fixtures/— Redacted JSON fixtures for model and formatting tests.
Tool catalog
The server exposes nine read-only tools:
Tool | Purpose |
| List events with optional future-only, |
| Fetch one event by |
| List dates/sessions for an |
| List orders for an |
| Fetch one order by |
| List tickets for an |
| Fetch one ticket by |
| Get check-in totals for an |
| Summarise tickets for an |
Tag tools are intentionally not included: the live CHCon account returned no tags when queried with a read-only key on 15 August 2026.
All list tools support page_size (1-100) and max_items (default 500). All
data-returning tools support raw=true to return the full Humanitix payload
instead of the trimmed summary.
override_location is forwarded to Humanitix as overrideLocation. Use it
when events are associated with a different market (for example, an NZ
account); the default location filter can legitimately omit an event.
Verified public CHCon 2025 smoke target
The opt-in, read-only smoke test verified this public event identifier on 15 August 2026:
Event:
6875f6fd6e7ba808d7baa311
The direct API title expands the CHCon name as “Christchurch Hacker Con and
Training Day 2025”; the smoke test accepts that expanded public name or a
literal case-insensitive chcon name and derives date identifiers at runtime.
It exercised every read-only tool, including raw structural identifier checks
for order and ticket lists. The BETA check-in endpoint is unstable: it may
return a structured 5xx service outcome even when the tool request is valid.
Troubleshooting
Humanitix 401: Confirm
HUMANITIX_API_KEYis set in local.env, was obtained from the official key page above, and has not been replaced; then restart the MCP client. Do not share the key while investigating.Missing events: Try the appropriate
override_location; Humanitix applies location filtering throughoverrideLocation.Cold starts: The first
uv runor MCP request can take longer while the environment starts. Wait for the stdio client to connect and retry rather than treating a startup delay as an API failure.Empty results: An empty event, order, ticket, or tag collection can be a valid account/data-availability result. The smoke account had zero tags, so no tag tools are exposed.
BETA check-in: Treat a structured 5xx result from
humanitix_get_check_in_countas an unstable service outcome, not a reason to retry with altered identifiers.Claude OAuth 401: This is authentication to the local Claude CLI, not the Humanitix API. Re-authenticate Claude, verify
claude mcp list, and retry the tool call.
Read-only boundary
The server only implements read-only tools. No write endpoints, check-in/check-out actions, transfers, or network listeners are exposed.
Structured errors
Expected failures are returned as JSON dictionaries with success: false and a
human-readable error message. This covers missing configuration, invalid
arguments, authentication, authorization, not-found, validation, server, and
transport failures. Error messages never include the API key or raw tracebacks.
Running tests
uv run pytestImplementation status
Phase 1: Scaffold
Phase 2: HTTP client (
client.py)Phase 3: Response models and trimming (
models.py,formatting.py)Phase 4: MCP server and tools (
server.py)Phase 5: Live smoke test (15 August 2026)
Phase 6: Claude Cowork sales-summary verification (blocked on local Claude OAuth 401 before an MCP call)
Phase 7: Documentation
License
MIT
Available Tools
9 toolshumanitix_get_check_in_countA
Get check-in totals for a Humanitix event and event date. The event_id identifies the event; event_date_id identifies its specific date and can be obtained from humanitix_list_event_dates. Warning: the /check-in-count endpoint is BETA and its response shape may change. Returns trimmed counts by default; set raw=true for the full payload.
Inputs: event_id (required), event_date_id (required), raw.
humanitix_get_eventA
Fetch a single Humanitix event by its event identifier. Returns the trimmed event by default; set raw=true for the full payload.
Inputs: event_id (required), raw, override_location.
humanitix_get_orderA
Fetch a single order by its event identifier and order identifier. Returns a trimmed order by default; set raw=true for the full payload.
Inputs: event_id (required), order_id (required), raw, override_location.
humanitix_get_ticketA
Fetch a single ticket by its event identifier and ticket identifier. Returns a trimmed ticket by default; set raw=true for the full payload.
Inputs: event_id (required), ticket_id (required), raw, override_location.
humanitix_list_event_datesA
List the event dates (sessions) belonging to a Humanitix event. Event dates are required identifiers for orders, tickets, and check-in tools. Returns a projection of each date with its id, name, and start/end times.
Inputs: event_id (required), raw, override_location.
humanitix_list_eventsA
List Humanitix events accessible to the configured API key. Returns trimmed event summaries by default; set raw=true to receive the full Humanitix payload. Results are paginated and capped at max_items (default 500). Use in_future_only=true to retrieve only events whose end date is in the future, or provide an ISO 8601 datetime via since.
Inputs: raw, since, max_items, page_size, +2 more.
humanitix_list_ordersA
List orders for a specific Humanitix event and event date. The event_id identifies the event; event_date_id identifies its specific date and can be obtained from humanitix_list_event_dates. Returns trimmed orders by default; set raw=true for full payloads.
Inputs: event_id (required), event_date_id (required), raw, since, +3 more.
humanitix_list_ticketsA
List tickets for a specific Humanitix event and event date. The event_id identifies the event; event_date_id identifies its specific date and can be obtained from humanitix_list_event_dates. Optionally filter by ticket status. Returns trimmed tickets by default; set raw=true for full payloads.
Inputs: event_id (required), event_date_id (required), raw, since, +4 more.
humanitix_sales_summaryA
Build a sales summary for a Humanitix event and event date by aggregating tickets. Reports sold/complete counts, cancelled counts, gross revenue (when price data is available), and capacity utilisation (when a trustworthy capacity value is present). The event_id identifies the event; event_date_id identifies its specific date and can be obtained from humanitix_list_event_dates.
Inputs: event_id (required), event_date_id (required), raw, max_items, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a clearly distinct resource and action (list vs get for events, orders, tickets), and the analytics tools (check-in count, sales summary) are unambiguous. There is no meaningful overlap between any pair of tools.
Nearly all tools follow a consistent humanitix_verb_noun pattern (list_events, get_order, list_tickets). The only deviation is sales_summary, which is a noun phrase without a verb, but the shared prefix keeps the set predictable.
Nine tools is well-scoped for an event/ticketing read API, with each tool earning its place across events, dates, orders, tickets, and analytics.
The surface covers the core read lifecycle: events, event dates, orders, tickets, check-in totals, and sales aggregation. Only minor gaps exist (e.g. no single event-date fetch), which agents can work around via the list tool.
Maintenance
Related MCP Connectors
Unofficial remote MCP server for Less Annoying CRM: OAuth 2.1, read-only grants, 10 tools.
One OAuth connector for your team's remote MCP servers, with Tool Packs, guardrails and logs.
TheSignup MCP server — read and manage signups, participants, webhooks, and analytics.
Eventify MCP server — manage events, attendees, sessions, speakers, sponsors, and analytics.
Related MCP Servers
- AlicenseBqualityDmaintenanceRead-only MCP server for the Humaans HRIS API, providing tools to query people, reporting chains, compensation, time away, and more.33MIT
- AlicenseAqualityDmaintenanceRead-only MCP server for the HIT ticket management system that lists queues, searches/fetches ticket details, and lists ticket templates.41MIT
- FlicenseBqualityDmaintenanceAn MCP server that wraps the TryBooking Reporting API, enabling AI assistants like Claude to query bookings, events, sales reports, and attendance scans.15-
- FlicenseNot gradedqualityDmaintenanceFull MCP server for the Eventbrite API with 73 tools to manage events, attendees, orders, tickets, venues, discounts, reports, webhooks, and more.-