# framedeck-mcp

MCP server for [Framedeck](https://framedeck.app) — connect any AI assistant to your content production pipeline.

Works with **Claude**, **ChatGPT**, **Gemini**, **Copilot**, and any MCP-compatible client.

## Quick Start

1. Get your API key at [framedeck.app](https://framedeck.app) > Settings > API Keys
2. Add to your AI assistant config (see below)

## Setup

### Claude Code

```bash
claude mcp add framedeck -e FRAMEDECK_API_KEY=your_key_here -- npx -y framedeck-mcp
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "framedeck": {
      "command": "npx",
      "args": ["-y", "framedeck-mcp"],
      "env": {
        "FRAMEDECK_API_KEY": "your_key_here"
      }
    }
  }
}
```

### Other MCP Clients

Set the environment variable `FRAMEDECK_API_KEY` and run:

```bash
npx framedeck-mcp
```

## Usage Examples

Talk to your AI assistant naturally — here are three end-to-end workflows:

### Example 1 — Capture and graduate ideas

> **You:** *"I just had 3 video ideas: a knife sharpening tutorial, a Sony A7IV review, and a day-in-the-life vlog. Add them to my idea pool."*
>
> **Claude (via MCP):** Calls `create_multiple_cards` with the three titles. They land in your Idea Pool's "Ideas" stage.
>
> **You:** *"The knife sharpening one is a go — graduate it to a real production."*
>
> **Claude:** Calls `graduate_to_production` which creates a new dedicated production with full stages (Idea → Scripting → Filming → Editing → Published) and moves the idea card across.

### Example 2 — Plan a production day

> **You:** *"For the Sony review, add subtasks: write intro, shoot product shots, record voiceover, edit B-roll, color grade, export final."*
>
> **Claude:** Calls `set_active_board` to "Sony A7IV review", then `create_multiple_cards` with all six subtasks in the "Filming" stage.
>
> **You:** *"Mark the intro and product shots as done."*
>
> **Claude:** Calls `move_card` twice to push them into the "Done" stage.

### Example 3 — Get a project overview

> **You:** *"How's my channel looking? Anything overdue?"*
>
> **Claude:** Calls `get_board_overview` for each production. Returns a summary showing card counts per stage, overdue items highlighted in red, and which productions need attention.
>
> **You:** *"What's assigned to me right now?"*
>
> **Claude:** Calls `get_my_cards` and lists everything you own grouped by board and status.

## Tools (32)

| Tool | Description |
|------|-------------|
| `set_active_board` | Set the active production context |
| `get_active_board` | Show current active production |
| `list_boards` | List all productions/projects |
| `create_board` | Create a new production or project |
| `list_columns` | List stages in a board |
| `create_column` | Create a new stage |
| `delete_column` | Delete a stage |
| `list_cards` | List cards/frames with filters |
| `create_card` | Create a card/frame |
| `create_multiple_cards` | Batch create (up to 50) |
| `update_card` | Update title, description, priority, due date |
| `move_card` | Move to a different stage |
| `delete_card` | Permanently delete |
| `archive_card` | Soft delete (restorable) |
| `duplicate_card` | Copy with checklist and labels |
| `set_card_color` | Color-code a card |
| `add_comment` | Add a comment |
| `add_checklist_item` | Add a subtask |
| `toggle_checklist_item` | Check/uncheck a subtask |
| `add_labels_to_card` | Add labels to a card |
| `remove_label_from_card` | Remove a label |
| `get_card_details` | Full card info |
| `search_cards` | Search by keyword |
| `assign_card` | Assign a team member |
| `get_my_cards` | Cards grouped by status |
| `get_board_overview` | Board summary with overdue items |
| `list_labels` | List all labels |
| `create_label` | Create a label |
| `link_commit` | Link a git commit to a card |
| `log_work` | Log time spent |
| `get_sprint_summary` | Activity summary |
| `graduate_to_production` | Promote idea to full production |

## Dual Mode

Framedeck supports two board modes:

- **Creator mode**: Productions, Stages, Frames — for content pipelines
- **Classic mode**: Projects, Stages, Cards — for standard project management

The MCP server automatically uses the correct terminology based on each board's mode.

## Idea Pool

When you add ideas without specifying a board, they automatically land in your **Idea Pool**. When an idea is ready, use `graduate_to_production` to create a dedicated production with full stages (Idea > Scripting > Filming > Editing > Published).

## Safety Annotations

Every tool ships with MCP safety annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so AI clients can warn users before destructive actions like `delete_card`, `delete_column`, and `archive_card`.

## Privacy & Support

- **Privacy Policy:** https://framedeck.app/privacy
- **Terms of Service:** https://framedeck.app/terms
- **Support:** support@framedeck.app
- **Issues:** https://github.com/Lukaris/framedeck-mcp/issues

## License

MIT