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