# Planning Center Online MCP Server

An MCP (Model Context Protocol) server for the [Planning Center Online](https://www.planningcenter.com) API. Enables AI assistants like Claude to interact with your PCO account across all major modules.

## Covered Modules

| Module | Tools |
|--------|-------|
| **People** | List/search people, get person, create/update person, emails, phone numbers, households, lists |
| **Services** | Service types, plans, songs, teams, series |
| **Giving** | Donations, funds, batches |
| **Groups** | Groups, group types, members |
| **Calendar** | Events, event instances, resources/rooms |
| **Check-Ins** | Check-ins, events, locations |

## Authentication

Planning Center uses **Personal Access Tokens** for single-account access. Get yours at:
[https://api.planningcenteronline.com/oauth/applications](https://api.planningcenteronline.com/oauth/applications)

You'll receive an **Application ID** and **Secret** — set these as environment variables.

## Setup

### 1. Build

```bash
npm install
npm run build
```

### 2. Configure Claude Desktop (or Claude Code)

Add the following to your MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "planning-center": {
      "command": "node",
      "args": ["/path/to/planning-center-mcp-server/dist/index.js"],
      "env": {
        "PCO_APP_ID": "your_application_id",
        "PCO_SECRET": "your_secret"
      }
    }
  }
}
```

### 3. Run (stdio mode, for Claude Desktop)

```bash
PCO_APP_ID=your_app_id PCO_SECRET=your_secret npm start
```

### 4. Run (HTTP mode, for remote/multi-client)

```bash
PCO_APP_ID=your_app_id PCO_SECRET=your_secret TRANSPORT=http PORT=3000 npm start
# Server available at http://localhost:3000/mcp
```

## Available Tools

### People (`/people/v2`)

| Tool | Description |
|------|-------------|
| `pco_list_people` | Search/list people with filters (name, status, gender, child) |
| `pco_get_person` | Get full person record with emails, phones, addresses |
| `pco_create_person` | Create a new person record |
| `pco_update_person` | Update an existing person (sparse update) |
| `pco_list_person_emails` | List email addresses for a person |
| `pco_list_person_phone_numbers` | List phone numbers for a person |
| `pco_list_households` | List households |
| `pco_list_people_lists` | List smart lists (saved filters) |

### Services (`/services/v2`)

| Tool | Description |
|------|-------------|
| `pco_list_service_types` | List all service types |
| `pco_list_plans` | List plans for a service type (filter: future/past) |
| `pco_get_plan` | Get full plan details |
| `pco_list_songs` | List/search song library |
| `pco_list_teams` | List teams for a service type |
| `pco_list_series` | List sermon series for a service type |

### Giving (`/giving/v2`)

| Tool | Description |
|------|-------------|
| `pco_list_donations` | List donations (filter by date, method, status) |
| `pco_get_donation` | Get donation details |
| `pco_list_funds` | List giving funds |
| `pco_list_donation_batches` | List donation batches |

### Groups (`/groups/v2`)

| Tool | Description |
|------|-------------|
| `pco_list_groups` | List/search groups |
| `pco_get_group` | Get group details |
| `pco_list_group_members` | List group members/leaders |
| `pco_list_group_types` | List group types |

### Calendar (`/calendar/v2`)

| Tool | Description |
|------|-------------|
| `pco_list_calendar_events` | List events (filter: approved/pending/future/past) |
| `pco_get_calendar_event` | Get event details with instances |
| `pco_list_event_instances` | List occurrences of a calendar event |
| `pco_list_calendar_resources` | List facility resources/rooms |

### Check-Ins (`/check_ins/v2`)

| Tool | Description |
|------|-------------|
| `pco_list_checkins` | List check-in records (filter by date) |
| `pco_list_checkin_events` | List check-in events |
| `pco_list_checkin_locations` | List locations for a check-in event |

## Example Conversations

Once connected, you can ask Claude:

- *"Show me all active people added in the last month"*
- *"What plans are scheduled for next Sunday?"*
- *"List all donations received in January over $500"*
- *"How many members does the Young Adults small group have?"*
- *"What calendar events are coming up this week?"*
- *"Show me the children's check-in locations"*

## Development

```bash
# Watch mode for development
npm run dev

# Clean build artifacts
npm run clean
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PCO_APP_ID` | ✅ | Planning Center Application ID |
| `PCO_SECRET` | ✅ | Planning Center Secret |
| `TRANSPORT` | No | Set to `http` for HTTP mode (default: stdio) |
| `PORT` | No | HTTP port (default: 3000, HTTP mode only) |

## API Reference

- [Planning Center Developer Docs](https://developer.planning.center/docs/)
- [PCO API Explorer](https://api.planningcenteronline.com/oauth/applications)
- [JSON API 1.0 Spec](https://jsonapi.org)