JinDaGe - planning-center-mcp MCP Details

article

README

🚀 规划中心MCP服务器

这是一个FastMCP服务器，为规划中心人员API提供工具。该服务器实现了MCP（模型上下文协议）工具，可根据JSON API规范1.0从规划中心查询和过滤人员数据。

🚀 快速开始

安装依赖

本项目使用 uv 进行依赖管理：

uv sync

配置环境变量

复制示例环境文件并添加你的规划中心凭证：

cp .env.example .env

编辑 .env 文件，添加你的规划中心API凭证：

PLANNING_CENTER_CLIENT_ID=your_client_id_here
PLANNING_CENTER_SECRET=your_secret_here

获取规划中心API凭证

访问 https://api.planningcenteronline.com/oauth/applications
创建一个新应用
将客户端ID和密钥复制到你的 .env 文件中

运行MCP服务器

uv run planning-center-mcp

或者直接使用Python运行：

uv run python main.py

✨ 主要特性

MCP服务器提供了以下用于查询规划中心数据的工具：

list_people_with_approved_background_checks：获取所有背景调查通过的人员
list_people_with_role：查找具有特定角色的人员
list_people_by_age_range：按年龄范围过滤人员
list_people_by_gender：按性别过滤人员
list_people_with_household：获取属于某个家庭的人员
list_people_in_family：查找具有特定家庭/姓氏的人员
list_people_with_membership：获取具有特定会员类型的人员
search_people：按姓名、电子邮件或其他识别信息搜索人员
get_person_details：获取特定人员的详细信息

📚 详细文档

与Claude桌面集成

要在Claude桌面中使用此MCP服务器，请在Claude桌面配置文件中添加以下配置：位置：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "planning-center": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/eric.foster/projects/plan-cp",
        "planning-center-mcp"
      ]
    }
  }
}

将 /Users/eric.foster/projects/plan-cp 替换为你项目目录的实际路径。

速率限制

规划中心每分钟有100个请求的速率限制。MCP服务器会通过跟踪请求自动处理此限制，如果超过限制则会抛出错误。

API合规性

此服务器设计为与规划中心的JSON API规范1.0配合使用，根据规范处理适当的过滤、查询和数据格式化。

🔧 技术细节

项目结构

planning-center-mcp/
├── main.py              # 主要的MCP服务器实现
├── pyproject.toml       # 项目配置和依赖项
├── .env.example         # 示例环境变量
├── .env                 # 你的环境变量（不在git中）
├── .gitignore          # Git忽略文件
└── README.md           # 此文件

测试

你可以通过运行MCP服务器并检查日志来在本地测试它。如果未提供真实凭证，服务器将使用演示凭证，但功能会受到限制。

📄 许可证

本项目是开源的。有关详细信息，请参阅许可证文件。

💡 使用建议

故障排除

身份验证问题：确保你的规划中心凭证已正确设置在 .env 文件中。
速率限制：如果你遇到速率限制，请等待一分钟后再进行更多请求。
连接问题：检查你的互联网连接和规划中心API状态。

planning-center-mcp