Planning Center MCP

🚀 規劃中心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憑證

1. 訪問 https://api.planningcenteronline.com/oauth/applications
2. 創建一個新應用
3. 將客戶端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服務器並檢查日誌來在本地測試它。如果未提供真實憑證，服務器將使用演示憑證，但功能會受到限制。

📄 許可證

本項目是開源的。有關詳細信息，請參閱許可證文件。

💡 使用建議

故障排除

1. 身份驗證問題：確保你的規劃中心憑證已正確設置在 .env 文件中。
2. 速率限制：如果你遇到速率限制，請等待一分鐘後再進行更多請求。
3. 連接問題：檢查你的互聯網連接和規劃中心API狀態。