ChurchSuite Bookings

Tests License: MIT

A lightweight FastMCP server that exposes read-only ChurchSuite booking data as MCP tools.

Setup

1. Create an API-enabled user or an OAuth App in ChurchSuite to obtain a Client ID and Client Secret (see ChurchSuite auth docs). Grant it the bookings.read, rotas.read, and addressbook.read scopes.

2. Install dependencies:

   uv sync
   

3. Copy .env.example to .env and fill in your credentials, or export the variables directly:

   export CHURCHSUITE_CLIENT_ID=...
   export CHURCHSUITE_CLIENT_SECRET=...
   

4. Run the server:

   uv run churchsuite-mcp
   

Tools

• list_bookings(status?, starts_after?, starts_before?, customer_ids?, type_ids?, q?, page?, per_page?) — list bookings with optional filters.
• get_booking(id) — fetch a single booking by ID.
• list_booked_resources(booking_ids?, page?, per_page?) — list resources booked against bookings.
• list_resources(category?, q?, status?, page?, per_page?) — list bookable resources (rooms, equipment, etc.).
• get_resource(id) — fetch a single bookable resource by ID.
• list_ministries(statuses?, q?, ids?, page?, per_page?) — list Rotas ministries.
• get_ministry(id) — fetch a single ministry, including its serving days/time/rotation type.
• list_ministry_teams(ministry_ids?, team_ids?, page?, per_page?) — list teams within ministries.
• get_ministry_team(id) — fetch a single ministry team.
• list_ministry_members(ministry_ids?, role_ids?, team_ids?, page?, per_page?) — list ministry members.
• list_rota_roles(member_ids?, ministry_ids?, page?, per_page?) — list roles defined within ministries.
• find_serving_pattern(person_id, person_type) — find a person's ministry memberships and their recurring serving pattern (days/time/rotation type).

Note on rotas: ChurchSuite's API v2 does not expose individual rota slot assignments or dates — only ministry membership and a ministry's recurring schedule definition. find_serving_pattern is the closest available answer to "when am I next serving?": it returns the ministries/ teams/roles a person belongs to and how often that ministry serves, not a confirmed next date.

Using with an MCP client

Add to your client's MCP config (e.g. .mcp.json for Claude Code):

{
  "mcpServers": {
    "churchsuite-bookings": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/churchsuite-mcp", "churchsuite-mcp"],
      "env": {
        "CHURCHSUITE_CLIENT_ID": "your-client-id",
        "CHURCHSUITE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude chat (desktop app)

To add this as a local MCP server in the Claude desktop app, open Settings → Developer → Edit Config to locate claude_desktop_config.json, then add the same churchsuite-bookings entry under mcpServers:

{
  "mcpServers": {
    "churchsuite-bookings": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/churchsuite-mcp", "churchsuite-mcp"],
      "env": {
        "CHURCHSUITE_CLIENT_ID": "your-client-id",
        "CHURCHSUITE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Replace /path/to/churchsuite-mcp with the absolute path to this project (e.g. /Users/steve/churchsuite-mcp), fill in your real Client ID/Secret, then restart Claude for the change to take effect.

Auth

Authentication uses the OAuth2 Client Credentials grant against https://login.churchsuite.com/oauth2/token. Access tokens are cached in memory and transparently refreshed before they expire.