A comprehensive, modern Python wrapper for the Planning Center API using Pydantic and async/await patterns. This library provides type-safe access to all Planning Center products including People, Services, Check-Ins, Giving, Groups, and Calendar.
🚀 Features
Type-safe with full Pydantic models for all data structures
Python wrapper and MCP server for the Planning Center API for churches.
Stars
4
Tools
—
Uptime
—
Async/await support using httpx for modern Python patterns
Webhook native with built-in signature verification and event handling
All Products supported: People, Services, Check-Ins, Giving, Groups, Calendar, Publishing, Webhooks, Organization
Auto-pagination for seamless handling of large datasets
Rate limiting with automatic exponential backoff
Comprehensive error handling with specific exception types
CLI tools for common operations
Utility functions for data processing and analysis
MCP Server for AI assistant integration with 80+ tools including advanced analytics
📦 Installation
Core API Package
# Install with uv (recommended)
cd planning-center-api
uv pip install "planning_center_api@."
# Or with pip
cd planning-center-api
pip install .
MCP Server (Optional)
For AI assistant integration:
# Install MCP server
cd planning-center-mcp-server
uv pip install "planning_center_mcp@."
# Or with pip
cd planning-center-mcp-server
pip install .
🛠 Quick Start
Basic Usage
import asyncio
from planning_center_api import PCOClient, PCOProduct
async def main():
async with PCOClient(app_id="your_app_id", secret="your_secret") as client:
# Get all people with emails
people = await client.get_people(include=["emails"])
# Create new person
person = await client.create_person({
"first_name": "John",
"last_name": "Doe"
})
# Auto-paginate through all services
async for service in client.paginate_all(
product=PCOProduct.SERVICES,
resource="services"
):
print(f"Service: {service.attributes.get('title')}")
asyncio.run(main())
Authentication
The library supports both OAuth 2.0 and Personal Access Token authentication:
async with PCOClient(
app_id="your_app_id",
secret="your_secret",
access_token="your_token", # Alternative to app_id/secret
webhook_secret="your_webhook_secret"
) as client:
# Use client here
# Auto-paginate through all resources
async for person in client.paginate_all(
product=PCOProduct.PEOPLE,
resource="people",
per_page=25
):
print(person.get_full_name())
Product-Specific Methods
People
# Get people
people = await client.get_people(per_page=50, include=["emails", "phone_numbers"])
person = await client.get_person("person_id", include=["emails"])
# Search and filter
results = await client.search_people("john")
email_results = await client.get_people_by_email("[email protected]")
active_people = await client.get_active_people()
# Create and update
person = await client.create_person({
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]"
})
updated = await client.update_person("person_id", {"phone": "555-123-4567"})
Services
# Get services and plans
services = await client.get_services(per_page=25)
service = await client.get_service("service_id")
plans = await client.get_plans(service_id="service_id")
plan = await client.get_plan("plan_id")
🖥 CLI Usage
The library includes a comprehensive CLI tool:
# Get people
pco-cli get --product people --resource people --per-page 10
# Search people
pco-cli search-people --query "john" --output table
# Create a person
pco-cli create --product people --resource people --data '{"first_name": "John", "last_name": "Doe"}'
# Paginate through all services
pco-cli paginate --product services --resource services --output csv
# Find by email
pco-cli find-by-email --email "[email protected]"
🤖 MCP Server for AI Assistants
The repository includes a comprehensive Model Context Protocol (MCP) server that exposes all major Planning Center APIs as tools for AI assistants like Claude, Cursor, and other MCP-compatible clients.
🚀 Features
Comprehensive Coverage: 80+ read-only tools across 9 Planning Center products
Native MCP Integration: Built using the official MCP protocol for seamless AI assistant integration
Read-only operations for data safety
Mock server included for testing without API credentials
Claude Desktop ready with pre-configured setup
Advanced filtering and pagination support
Advanced Analytics: 10+ specialized analytics tools for data-driven insights
Event attendee filtering for enhanced event management
# Navigate to MCP server directory
cd planning-center-mcp-server
# Run the mock server
uv run python mcp_mock_server_comprehensive.py
# Or use the batch file
run_comprehensive_server.bat
Option 2: Real Server (Requires API Credentials)
For production use with real Planning Center data:
# Set up environment variables
cp env.example .env
# Edit .env with your Planning Center API credentials
# Run the real server
uv run python mcp_server_fixed.py
# Or use the batch file
run_real_server.bat
🤖 Claude Desktop Integration
The servers are pre-configured for Claude Desktop integration:
Edit your Claude Desktop config: %APPDATA%\Claude\claude_desktop_config.json
Add server configuration (already done if you followed the setup)
Restart Claude Desktop
Start asking questions about Planning Center data!
Available in Claude Desktop
Mock Server: planning-center-mock (no credentials needed)
Real Server: planning-center-api (requires API credentials)
💡 Usage Examples
Once configured, you can ask Claude questions like:
"Show me all active people in our database"
"Get the attendees for Summer Camp 2024"
"Find all donations from last month"
"List all groups and their members"
"Show me upcoming calendar events"
🎭 Mock Server Features
14+ tools covering the most commonly used endpoints
Realistic fake data with proper relationships between entities
The library provides specific exception types for different error scenarios:
from planning_center_api.exceptions import (
PCOError,
PCOAuthenticationError,
PCOPermissionError,
PCONotFoundError,
PCOValidationError,
PCORateLimitError,
PCOServerError
)
try:
person = await client.get_person("invalid_id")
except PCONotFoundError:
print("Person not found")
except PCOAuthenticationError:
print("Authentication failed")
except PCORateLimitError as e:
print(f"Rate limited. Retry after: {e.retry_after}")
except PCOError as e:
print(f"API error: {e.message}")
📊 Data Models
All data is returned as Pydantic models with type safety:
# Resource models
person = await client.get_person("person_id")
print(person.get_first_name()) # Type-safe access
print(person.get_email())
print(person.get_full_name())
# Collection models
people = await client.get_people()
print(len(people)) # Collection length
for person in people: # Iterable
print(person.get_full_name())
# Access included resources
person = await client.get_person("person_id", include=["emails"])
emails = person.get_relationship_data("emails")
🔄 Rate Limiting
The library automatically handles rate limiting with exponential backoff:
# Rate limiting is handled automatically
# You can configure it in PCOConfig
config = PCOConfig(
rate_limit_requests=100, # Requests per window
rate_limit_window=60, # Window in seconds
max_retries=3, # Max retry attempts
backoff_factor=2.0 # Exponential backoff factor
)
🧪 Testing
# Run tests
cd planning-center-api
pytest
# Run with coverage
pytest --cov=planning_center_api
# Run specific test file
pytest tests/test_client.py
📝 Examples
Check the planning-center-api/examples/ directory for comprehensive examples:
basic_usage.py - Basic API operations
webhook_server.py - FastAPI webhook server
data_export.py - Data export and analysis
advanced_usage.py - Advanced patterns and utilities
🛠 Development
Setup
# Clone the repository
git clone <repository-url>
cd planningcenter-wrapper
# Install development dependencies
cd planning-center-api
uv sync --group dev
# Run linting
uv run ruff check --fix planning_center_api/
# Run tests
uv run pytest
Project Structure
planningcenter-wrapper/
├── planning-center-api/ # Core API package
│ ├── planning_center_api/ # Source code
│ ├── examples/ # Usage examples
│ ├── tests/ # Test suite
│ ├── docs/ # Documentation
│ └── pyproject.toml # Package configuration
├── planning-center-mcp-server/ # Comprehensive MCP server for AI assistants
│ ├── planning_center_mcp/ # MCP server source code
│ ├── mcp_server_fixed.py # Real server with 65+ tools
│ ├── mcp_mock_server_comprehensive.py # Mock server for testing
│ ├── run_real_server.bat # Batch file for real server
│ ├── run_comprehensive_server.bat # Batch file for mock server
│ ├── README.md # Comprehensive MCP server documentation
│ ├── COMPREHENSIVE_API_COVERAGE.md # Complete API coverage documentation
│ ├── CLAUDE_DESKTOP_SETUP.md # Claude Desktop setup guide
│ ├── QUICKSTART.md # Quick start guide
│ └── pyproject.toml # MCP server configuration
├── _apis/ # API documentation
└── README.md # This file
🤝 Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.