churchtools-mcp-server

An MCP server for ChurchTools that bundles ChurchTools API documentation at build time and exposes tools for:

querying a configured ChurchTools instance with a login token
searching the bundled OpenAPI spec and inspecting operations
searching bundled ChurchTools internal rights documentation
searching ChurchTools Academy and reading Academy articles
giving the model reusable prompt-based workflows for investigation, API validation, and rights checks

Features

Build-time ingestion of ../churchtools/docs/openApi/openapi.yaml
Build-time download of https://academy-assets.church.tools/system/runtime/authdoc.html
Live API calls against a configured ChurchTools instance using Authorization: Login <token>
Live ChurchTools Academy search via BetterDocs
Static MCP resources for bundled docs and server configuration
Prompt templates that act like reusable ChurchTools investigation skills
Modular TypeScript structure so new tools and resources can be added without touching the transport layer

Configuration

The server reads its configuration from environment variables:

CHURCHTOOLS_BASE_URL - your ChurchTools base URL, for example https://example.church.tools
CHURCHTOOLS_LOGIN_TOKEN - a ChurchTools login token used as Authorization: Login <token>
CHURCHTOOLS_ACADEMY_LOCALE - optional, defaults to de
CHURCHTOOLS_ANONYMIZE_PERSONAL_DATA - optional, defaults to true; set to false to pass live API responses through without anonymizing person and address data

When anonymization is enabled, live churchtools_api_request responses are sanitized on the MCP layer before they are returned to the model. The sanitizer targets ChurchTools person and address payloads, including Person, DomainObjectPerson, DomainObjectExternalPerson, DomainObjectGroupMembership, Address, and AddressSearchResult-style structures.

Privacy Disclaimer

This project anonymizes sensitive data on a best-effort basis only. It is designed to reduce exposure of personal and other sensitive data to LLMs, but it cannot guarantee complete protection in every response shape or free-text field.

You remain responsible for assessing whether the software is appropriate for your privacy and compliance requirements. See DISCLAIMER.md for the full privacy and liability disclaimer.

Run From Npm

Published usage:

npx -y churchtools-mcp-server

Inside the repository after building:

npm run churchtools-mcp-server

MCP Client Example

{
  "mcpServers": {
    "churchtools": {
      "command": "npx",
      "args": ["-y", "churchtools-mcp-server"],
      "env": {
        "CHURCHTOOLS_BASE_URL": "https://example.church.tools",
        "CHURCHTOOLS_LOGIN_TOKEN": "your-login-token",
        "CHURCHTOOLS_ACADEMY_LOCALE": "de",
        "CHURCHTOOLS_ANONYMIZE_PERSONAL_DATA": "true"
      }
    }
  }
}

Development

Install dependencies:

npm install

Build the generated documentation bundle and the server:

npm run build

Run type-checking:

npm run check

Build-Time Inputs

By default, npm run build expects the ChurchTools monorepo to exist next to this repository and reads:

../churchtools/docs/openApi/openapi.yaml

If the file is somewhere else, override it with:

CHURCHTOOLS_OPENAPI_SOURCE=/absolute/path/to/openapi.yaml npm run build

The rights document source can also be overridden if needed:

CHURCHTOOLS_AUTHDOC_URL=https://academy-assets.church.tools/system/runtime/authdoc.html npm run build

Exposed MCP Capabilities

Tools

churchtools_api_request
churchtools_search_api
churchtools_get_api_operation
churchtools_search_rights
churchtools_get_rights_feature
churchtools_search_academy
churchtools_read_academy_article

Resources

churchtools://config/server
churchtools://docs/openapi.yaml
churchtools://docs/openapi-index.json
churchtools://docs/auth-rights.md
churchtools://docs/auth-rights.html

Prompt Workflows

churchtools_investigate_problem
churchtools_validate_api_shape
churchtools_check_permissions

MCP Servers