Skip to main content
Glama
kevinnz

humanitix-mcp

by kevinnz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

humanitix-mcp

A read-only MCP (Model Context Protocol) server for the Humanitix Public API.

This repository contains the completed Phase 1-4 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. Phase 5 live smoke testing is pending a real API key.

Setup

This project uses uv and requires Python 3.11+.

uv sync --extra dev

Copy .env.example to .env and add a real API key when available:

cp .env.example .env

The server reads HUMANITIX_API_KEY and HUMANITIX_BASE_URL from the environment. HUMANITIX_BASE_URL defaults to https://api.humanitix.com.

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

With the MCP Inspector:

npx @modelcontextprotocol/inspector uv run humanitix-mcp

The server creates one HumanitixClient per stdio connection and closes it when the connection ends.

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

humanitix_list_events

List events with optional future-only and since filters.

humanitix_get_event

Fetch one event by event_id.

humanitix_list_event_dates

List the dates/sessions for an event; event-date IDs are required by the order, ticket, and check-in tools.

humanitix_list_orders

List orders for a specific event date.

humanitix_get_order

Fetch one order by order_id.

humanitix_list_tickets

List tickets for a specific event date, optionally filtered by status.

humanitix_get_ticket

Fetch one ticket by ticket_id.

humanitix_get_check_in_count

Get check-in totals for an event date (BETA endpoint).

humanitix_sales_summary

Aggregate tickets for an event date into sold/cancelled counts, gross revenue (when price data is present), and capacity utilisation (when capacity is present).

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.

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 pytest

Implementation 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 (requires a real HUMANITIX_API_KEY and is not part of this phase)

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • humaans-mcp

    ptorsten
    A
    license
    B
    quality
    D
    maintenance
    Read-only MCP server for the Humaans HRIS API, providing tools to query people, reporting chains, compensation, time away, and more.
    33
    MIT

  • hit-mcp

    DevpeakAB
    A
    license
    A
    quality
    D
    maintenance
    Read-only MCP server for the HIT ticket management system that lists queues, searches/fetches ticket details, and lists ticket templates.
    4
    4 npm
    1
    MIT

  • TryBooking MCP Server

    marek-knappe
    F
    license
    B
    quality
    B
    maintenance
    An MCP server that wraps the TryBooking Reporting API, enabling AI assistants like Claude to query bookings, events, sales reports, and attendance scans.
    15
    -

  • Eventbrite MCP Server

    marek-knappe
    F
    license
    Not graded
    quality
    B
    maintenance
    Full MCP server for the Eventbrite API with 73 tools to manage events, attendees, orders, tickets, venues, discounts, reports, webhooks, and more.
    -