Planning Center MCP Server

A FastMCP server that exposes read-only tools for the Planning Center People API (JSON API 1.0). Point an MCP client (Claude Desktop, etc.) at it to query and filter people, households, background checks, lists, and more with natural language.

All 18 tools are read-only (GET requests only) — the server never creates, updates, or deletes data in your Planning Center account.

Features

People

• search_people — search for people by name
• list_people — general-purpose query (first/last name, status, created/updated since, ordering)
• list_people_by_gender — filter by gender
• list_people_by_age_range — filter by age (translated to a birthdate range)
• list_people_in_family — filter by family/last name
• list_people_with_membership — filter by membership value
• get_person_details — one person with households, emails, phone numbers, and addresses
• find_person_by_email — look up a person by email address
• get_person_contact_info — a person's emails, phone numbers, and addresses

Households

• list_people_with_household — people who belong to at least one household
• list_households — list households (optionally filtered by name)
• get_household_members — the people in a specific household

Background checks

• list_people_with_approved_background_checks — people with an approved check
• list_background_checks — background checks filtered by status and/or completed-date range

Lists & organization

• list_people_in_list — people belonging to a named People List (segment)
• list_people_lists — discover People Lists (id, name, total_people)
• list_campuses — the organization's campuses
• list_forms — forms (optionally active-only)

Requirements

• Python 3.10+
• uv for dependency management
• A Planning Center Personal Access Token (Application ID + Secret)

Setup

1. Install dependencies

uv sync

2. Configure credentials

Copy the example env file and fill in your Planning Center credentials:

cp .env.example .env

PLANNING_CENTER_CLIENT_ID=your_application_id_here
PLANNING_CENTER_SECRET=your_secret_here

Get credentials by creating a Personal Access Token at https://api.planningcenteronline.com/oauth/applications. The server authenticates using HTTP Basic auth (Application ID as username, Secret as password).

3. Run the server

# Console script (STDIO transport — for MCP clients)
uv run planning-center-mcp

# Equivalent module invocation
uv run python -m planning_center_mcp.server

Claude Desktop integration

Add the server to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "planning-center": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/planning-center-mcp",
        "planning-center-mcp"
      ]
    }
  }
}

Replace /absolute/path/to/planning-center-mcp with the path where you cloned this repo. The server reads credentials from the .env file in that directory; alternatively you can supply them via an "env" block in the config.

Testing

A smoke-test script connects to the server in-process (no external MCP client needed):

# List the registered tools and show whether credentials are configured
uv run python tests/test_tools.py

# Also call a read-only tool against the live API (requires a valid .env)
uv run python tests/test_tools.py --live
uv run python tests/test_tools.py --live --gender Female

Without credentials the server still boots and lists its tools; live calls return a clear HTTP 401 error (not a silent empty list) telling you to set your .env.

Running over HTTP (streamable transport)

uv run python run_http_server.py --port 8000

This exposes a streamable-HTTP MCP endpoint at http://localhost:8000/mcp. It is an MCP endpoint for MCP clients — it does not serve an OpenAPI/ReDoc REST UI. Point an MCP client at that URL, or use tests/test_tools.py for a quick check.

Behavior notes

• Errors are surfaced, not swallowed. A bad filter, invalid include, auth failure, or rate limit raises an error with the HTTP status and API detail so you can see what went wrong (instead of an empty result).
• Pagination. List tools page through results up to a max_records cap (default 500) using the JSON:API offset cursor.
• Rate limiting. Planning Center allows 100 requests/minute. The client enforces this limit locally and also reports server-side 429 responses.
• Age. The People API has no age attribute, so list_people_by_age_range converts ages to a birthdate range; people without a birthdate on file are excluded when an age filter is applied.
• Roles to Lists. Planning Center People has no "roles" concept, so role-style segmentation is served via People Lists (list_people_in_list / list_people_lists).

Project structure

planning-center-mcp/
├── planning_center_mcp/
│   ├── __init__.py
│   ├── server.py        # MCP server entrypoint (stdio / http transport)
│   ├── client.py        # API client (auth, rate limit, pagination, errors)
│   └── tools.py         # MCP tool definitions
├── tests/
│   └── test_tools.py    # In-process smoke test
├── run_http_server.py   # Convenience launcher for HTTP transport
├── pyproject.toml       # Project configuration and dependencies
├── .env.example         # Example environment variables
├── LICENSE
└── README.md

Troubleshooting

1. Authentication (401/403): confirm PLANNING_CENTER_CLIENT_ID and PLANNING_CENTER_SECRET are set correctly in .env.
2. Rate limiting (429): wait a minute before making more requests.
3. Empty results: a 200 with no data means no records matched — the tools raise on real errors, so an empty list is a genuine "no matches."

License

Released under the MIT License.