Planning Center MCP Server

An MCP (Model Context Protocol) server for Planning Center Online Services. Gives AI agents (Claude, etc.) direct access to your worship plans, song library, teams, and volunteer data.

Includes a built-in AI agent (ask_question) that accepts natural language questions and calls tools automatically using a local Ollama model.

Tools

AI Agent

| Tool | Description | |------|-------------| | ask_question | Ask a natural language question about your PCO data. Uses a local Ollama model to call the appropriate tools and return a human-readable answer. |

Services & Plans

| Tool | Description | |------|-------------| | get_service_types | List all service types | | get_plans | Paginated plans for a service type (most recent first) | | get_plan_items | Get songs, headers, and media in a plan | | get_plan_team_members | Get volunteers assigned to a plan | | get_plan_details | Get items and team members in one call |

Songs & Arrangements

| Tool | Description | |------|-------------| | get_songs | Paginated song library listing | | get_song | Get a song by ID or search by title | | get_song_schedules | Schedule history for a song | | get_arrangements | List arrangements, or get a specific one by ID | | get_keys_for_arrangement | Available keys for an arrangement | | get_arrangement_attachments | List file attachments (PDFs, audio, etc.) | | create_song | Create a new song |

File Visibility (Attachment Types)

| Tool | Description | |------|-------------| | get_attachment_types | List org-level file classification types | | create_attachment_type | Create custom types (Lead Sheet, Guitar Tab, etc.) | | get_team_positions | Get teams, positions, and their attachment type mappings | | map_positions_to_attachment_types | Assign which file types a position can see | | enable_attachment_types | Toggle position-based file visibility on a service type |

Reports (cached data)

Sync | Tool | Description | |------|-------------| | sync_pco_data | Sync PCO data (incremental by default, full=True for complete re-sync) | | get_sync_status | Check when the last sync occurred | | get_team_names | All team names from synced data |

Song Library | Tool | Description | |------|-------------| | song_usage_report | Ranked song play counts with optional date range and service type filters | | song_detail_report | Full song details: arrangements, key-per-schedule history | | song_key_usage_report | Keys ranked by frequency across all songs in a time period | | songs_by_key_report | All songs ever played in a specific key (e.g. G, Bb), ranked by count | | songs_not_played_report | Songs not played in the last N months — sorted by most recently used before the cutoff | | songs_played_together_report | Songs most frequently paired with a given song in the same service | | song_retirement_report | Songs that were played frequently in an older window but have since dropped off | | service_bpm_flow_report | Tempo (BPM) and key progression across recent services, in song order |

Service Plans | Tool | Description | |------|-------------| | service_plan_report | Recent plans with setlists (including key per song) and team rosters | | upcoming_services_report | Upcoming plans with confirmed / pending / declined team members | | service_position_report | Songs most commonly used in a given service position (intro, outro, middle) |

Volunteers & People | Tool | Description | |------|-------------| | volunteer_activity_report | Volunteer frequency with optional team and date filters | | volunteer_decline_report | Volunteers with the most declined requests, including decline rate | | person_song_keys_report | Keys used in plans where a person served, optionally filtered by role | | person_song_preferences_report | Songs played when a person served, optionally filtered by role |

---

AI Agent: `ask_question`

The ask_question tool runs a multi-step tool-calling loop using a local Ollama model. It selects and chains the appropriate tools automatically based on your question, then returns a concise, human-readable answer.

How It Works

Your question is sent to the Ollama model along with the schemas for 30 curated read-only tools
The model decides which tools to call and with what parameters
Tool results are fed back to the model
Steps 2–3 repeat (up to 10 iterations) until the model produces a final answer

Configuration

| Environment Variable | Default | Description | |---|---|---| | OLLAMA_URL | http://localhost:11434 | Ollama instance URL | | AGENT_MODEL | mistral-small3.1 | Model to use for tool calling |

Any model with tool-calling support works. Larger models (24B+) are significantly more reliable at multi-step reasoning. Tested with mistral-small3.1.

Example Questions

Song Library `` What are our top 10 most played songs over the last 6 months? When did we last play "How Great Is Our God"? What key do we usually play "Blessed Be Your Name" in? What songs have we not played in the last 3 months? What songs have we quietly dropped from rotation this year? ``

Keys & Setlist Planning `` What are the most popular keys we use? What songs can we do in G? What songs pair well with "Cornerstone"? What do we usually open with? What's our typical tempo arc through a service? ``

Service Plans `` What songs are in this Sunday's service? Show me the last 3 Sunday morning setlists with keys. Which upcoming services have open volunteer spots? What did we play on Easter? ``

Volunteers & Teams `` Who are our most active volunteers over the last 3 months? Who has been declining a lot of service requests lately? Who is on the worship team this Sunday? Which team positions are unfilled for next week? ``

Person-Specific `` What keys does [name] play in when on guitar? What songs does [name] tend to pick when leading worship? What teams does [name] serve on? ``

General `` When was the data last synced from Planning Center? What service types do we have? ``

Prompting Tips

Be specific with time ranges: "last 3 months" or "since January" works better than "recently"
Name songs directly: Use the song title as it appears in PCO for best results
Ask one thing at a time: Multi-part questions ("top songs AND who played last week") can confuse the model — ask them separately
For volunteers, specify the team: "Who is on the band this Sunday?" is clearer than "who is volunteering?"
Synced data vs live data: Reports (song usage, volunteer activity, upcoming services) query the local MongoDB cache — run a sync first if your data may be stale. Direct lookups (get_song, get_plans) hit PCO live.
The agent won't modify data: It only has access to read-only tools. Write operations (creating songs, assigning tags) must be called directly.

---

Setup

1. Get PCO API Credentials

Create a Personal Access Token at the PCO Developer Portal.

2. Configure

cp .env.example .env
# Edit .env with your PCO credentials, MongoDB password, and Ollama URL

3. Run with Docker (recommended)

docker compose up -d

The MCP endpoint will be available at http://localhost:8080/mcp.

4. Run Locally (alternative)

pip install .
planning-center-mcp

Requires a running MongoDB instance (set MONGO_URI in .env).

---

Connect to Claude

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "planning-center": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "planning-center": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

---

Architecture

PCO API ← pypco ─┬─ services.py   (direct API tools)
                 └─ sync.py ──── MongoDB ─┬─ queries.py ─ reports.py (cached reports)
                                          └─ llm.py (embeddings, optional AI summaries)

agent.py  ─ Ollama (tool-calling loop) ─ dispatches to any registered tool

Direct tools (services.py): Hit the PCO API live. No cache needed.
Report tools (reports.py): Query local MongoDB for aggregated data. Run sync_pco_data to refresh.
Sync (sync.py): Incremental by default — only fetches records updated since the last sync.
Agent (agent.py): Accepts a natural language question, builds an Ollama tool-calling loop over 30 curated read-only tools, and returns a plain-text answer.
AI features (llm.py): Optional. Enables AI-generated summaries via Ollama.

---

Development

pip install -e ".[dev]"
pytest

planning-center-mcp