规划中心Python（或：Python规划中心）
一个全面且现代的Python包装器，用于Planning Center API，采用Pydantic和async/await模式。此库提供类型安全的访问所有Planning Center产品，包括人员、服务、签到、奉献、小组和日历。
🚀 功能特点
- 类型安全 为所有数据结构提供完整的 Pydantic 模型
- Async/await 支持使用 httpx 以适应现代 Python 模式
- 原生Webhook 具有内置签名验证和事件处理功能
- 所有产品 支持的功能：人员、服务、签到、捐赠、群组、日历、发布、Webhooks（网络钩子）、组织
- 自动分页 为了无缝处理大型数据集
- 限速 具有自动指数退避功能
- 全面的错误处理 带有特定的异常类型
- 命令行界面（CLI）工具 用于常见操作
- 实用函数 用于数据处理和分析
- MCP 服务器 为AI助手集成80多种工具，包括高级分析功能
📦 安装
核心API包
# Install with uv (recommended)
cd planning-center-api
uv pip install "planning_center_api@."
# Or with pip
cd planning-center-api
pip install .MCP 服务器（可选）
对于AI助手的集成：
# Install MCP server
cd planning-center-mcp-server
uv pip install "planning_center_mcp@."
# Or with pip
cd planning-center-mcp-server
pip install .🛠 快速入门
基本用法
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())认证
该库同时支持OAuth 2.0和个人访问令牌（Personal Access Token）两种认证方式：
# OAuth 2.0 (recommended)
client = PCOClient(access_token="your_oauth_token")
# Personal Access Token
client = PCOClient(app_id="your_app_id", secret="your_secret")Webhook 处理
from fastapi import FastAPI, Request
from planning_center_api import PCOClient, handle_webhook_event
app = FastAPI()
client = PCOClient(webhook_secret="your_secret")
@app.post("/webhook")
async def webhook_handler(request: Request):
payload = await request.body()
signature = request.headers.get("x-pco-signature")
async def person_created(webhook_payload):
print(f"New person: {webhook_payload.resource.attributes}")
await handle_webhook_event(
client=client,
payload=payload.decode(),
signature=signature,
event_handlers={"people.created": person_created}
)
return {"status": "success"}📚 API 参考手册
核心客户端
PCOClient
规划中心API操作的主要客户端。
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通用的CRUD操作
# Get resources
people = await client.get(PCOProduct.PEOPLE, "people")
person = await client.get(PCOProduct.PEOPLE, "people", "person_id")
# Create resources
new_person = await client.create(PCOProduct.PEOPLE, "people", {
"first_name": "John",
"last_name": "Doe"
})
# Update resources
updated_person = await client.update(
PCOProduct.PEOPLE, "people", "person_id", {
"phone": "555-123-4567"
}
)
# Delete resources
success = await client.delete(PCOProduct.PEOPLE, "people", "person_id")分页
# 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())针对特定产品的方法
人们
# 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("john@example.com")
active_people = await client.get_active_people()
# Create and update
person = await client.create_person({
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com"
})
updated = await client.update_person("person_id", {"phone": "555-123-4567"})服务
# 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 使用方法
该库包含一个全面的命令行界面（CLI）工具：
# 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 "john@example.com"🤖 用于AI助手的MCP服务器
该存储库包含一个全面的模型上下文协议（MCP）服务器，该服务器提供了 所有主要的规划中心API 作为像Claude、Cursor以及其他MCP兼容客户端等AI助手的工具。
🚀 特点
- 全面覆盖9款规划中心产品中的80+款只读工具
- 原生MCP集成使用官方MCP协议构建，实现无缝集成AI助手
- 只读操作 为了数据安全
- 包含模拟服务器 用于测试，无需API凭据
- Claude Desktop 已准备就绪 带有预配置设置
- 高级过滤 以及分页支持
- 高级分析10+款专业分析工具，助力数据驱动洞察
- 活动参与者筛选 用于增强活动管理
📋 可用的MCP工具（80+种工具）
人物API （15种工具）
get_people，get_person，get_person_addresses，get_person_emails，get_person_phones，get_person_background_checks，get_field_definitions，get_forms，get_form，get_campuses，get_campus
服务API (12种工具)
get_services，get_service，get_plans，get_plan，get_songs，get_song，get_arrangements，get_arrangement，get_keys，get_key，get_teams，get_team，get_team_positions，get_team_position
注册API （5种工具）
get_registrations，get_registration，get_attendees，get_attendee，get_event_attendees
提供API （10个工具）
get_donations，get_donation，get_funds，get_fund，get_batches，get_batch，get_pledges，get_pledge，get_pledge_campaigns，get_pledge_campaign，get_recurring_donations，get_recurring_donation
群组API （8个工具）
get_groups，get_group，get_group_events，get_group_event，get_group_memberships，get_group_membership，get_group_types，get_group_type
日历API （2个工具）
get_calendar_events，get_calendar_event
签到API （4个工具）
get_check_in_events，get_check_in_event，get_locations，get_location
发布API （4个工具）
get_channels，get_channel，get_episodes，get_episode
Webhooks API （2个工具）
get_webhook_subscriptions，get_webhook_subscription
组织API （4个工具）
get_connected_applications，get_connected_application，get_oauth_applications，get_oauth_application
🚀 快速入门
选项1：模拟服务器（无需凭据）
非常适合测试和开发：
# 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选项2：真实服务器（需要API凭据）
用于生产环境并使用真实的规划中心数据：
# 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.batClaude桌面集成
服务器已预先配置以集成Claude Desktop：
- 编辑您的Claude桌面配置：
%APPDATA%\Claude\claude_desktop_config.json - 添加服务器配置 （如果您已按照设置步骤操作，则此步骤已完成）
- 重启Claude桌面版
- 开始提问 关于规划中心的数据！
可在Claude Desktop上使用
- 模拟服务器：
planning-center-mock（无需凭据） - 真实服务器：
planning-center-api（需要API凭证）
💡 使用示例
配置完成后，您可以向Claude提出以下问题：
- *“给我显示数据库中所有活跃的人员”*
- *“招募2024年夏令营的参与者”*
- *“查找上个月的所有捐赠”*
- *“列出所有群组及其成员”*
- *“显示即将发生的日历事件”*
🎭 模拟服务器功能
- 14+种工具 涵盖最常用的终端节点
- 逼真的虚假数据 实体之间具有适当的关系
- 无需认证 用于测试
- 相同的API结构 作为真实服务器
- MCP集成 用于AI助手测试
有关MCP服务器的详细文档，请参阅 规划中心-MCP服务器/README.md。
CLI 配置
设置环境变量或使用配置文件：
export PCO_APP_ID="your_app_id"
export PCO_SECRET="your_secret"
# or
export PCO_ACCESS_TOKEN="your_token"或者创建一个 config.json 文件：
{
"app_id": "your_app_id",
"secret": "your_secret",
"timeout": 30.0,
"max_retries": 3
}🚨 错误处理
该库为不同的错误场景提供了特定的异常类型：
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}")📊 数据模型
所有数据均以具有类型安全性的 Pydantic 模型形式返回：
# 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 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
)🧪 测试
# Run tests
cd planning-center-api
pytest
# Run with coverage
pytest --cov=planning_center_api
# Run specific test file
pytest tests/test_client.py📝 示例
检查一下 planning-center-api/examples/ 包含综合示例的目录：
basic_usage.py- 基本API操作webhook_server.py- FastAPI 网络钩子服务器data_export.py- 数据导出与分析advanced_usage.py- 高级图案和实用工具
🛠 开发
设置
# Clone the repository
git clone
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项目结构
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🤝 贡献
- 为仓库创建分支
- 创建一个特性分支
- 进行你的更改
- 添加测试
- 提交拉取请求
📄 许可证
此项目遵循MIT许可协议 - 详情请参阅LICENSE文件。
🆘 支持
- 全面的MCP服务器README文件 - 全面的API覆盖指南 - Claude 桌面版安装指南 - 快速入门指南
- 为错误或功能请求提交一个问题