AI Integration

Connect Waveboard to AI assistants like Claude or ChatGPT. Manage your projects, tasks, time tracking, and invoices directly through natural language.

Waveboard provides a full REST API that AI assistants can use. There are two approaches:

The MCP (Model Context Protocol) Server gives Claude direct access to all Waveboard operations. Instead of generating curl commands, Claude can actually execute actions: create tasks, start timers, generate invoices — all from your chat.

Option 1: Claude Desktop

The Claude Desktop app supports MCP servers natively. Once configured, every conversation can access your Waveboard data.

1. 1
   Clone the Waveboard repository (or just download the mcp-server folder) and install the dependencies:

   cd waveboard/mcp-server
   npm install
   npm run build

2. 2
   Open the Claude Desktop config file.

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows: %APPDATA%\Claude\claude_desktop_config.json
3. 3
   Add the Waveboard MCP server to the config:

   {
     "mcpServers": {
       "waveboard": {
         "command": "node",
         "args": ["/FULL/PATH/TO/waveboard/mcp-server/dist/index.js"],
         "env": {
           "WAVEBOARD_API_KEY": "sk_live_YOUR_KEY_HERE",
           "WAVEBOARD_URL": "https://waveboard.pipewave.de"
         }
       }
     }
   }

   Replace /FULL/PATH/TO/ with the actual absolute path to the mcp-server folder, and sk_live_YOUR_KEY_HERE with your API key.

4. 4
   Restart Claude Desktop. You should see a hammer icon in the chat input — that means the MCP tools are loaded. Start chatting!

Option 2: Claude.ai (Browser)

Waveboard runs a remote MCP server that you can connect to directly from claude.ai — no local setup needed.

1. 1
   Open Claude.ai and go to Settings → Integrations (or click the plug icon in a chat).
2. 2
   Add a new integration. Click "Add more" and enter the MCP server URL:

   https://waveboard.pipewave.de/mcp

3. 3
   Authenticate using your Waveboard API key as Bearer token. Go to Waveboard Settings → API to get your key.
4. 4
   Done! The Waveboard tools will now be available in every Claude conversation. Each user connects with their own API key, so everyone sees their own data.

Option 3: Claude Code (CLI)

Claude Code also supports MCP servers. Add Waveboard as a project-level MCP server:

1. 1
   Build the MCP server (same as above):

   cd waveboard/mcp-server
   npm install && npm run build

2. 2
   Add the MCP server to Claude Code. Run this in your terminal:

   claude mcp add waveboard -- node /FULL/PATH/TO/waveboard/mcp-server/dist/index.js

3. 3
   Set the environment variables. Add these to your shell profile (.zshrc / .bashrc):

   export WAVEBOARD_API_KEY="sk_live_YOUR_KEY_HERE"
   export WAVEBOARD_URL="https://waveboard.pipewave.de"

4. 4
   Start Claude Code and the Waveboard tools will be available. Ask Claude to list your projects, create tasks, track time, etc.

If you prefer not to use the MCP server, you can also add the API documentation as project knowledge in Claude.ai. Claude will then know all endpoints and generate curl commands for you to run manually.

1. 1
   Open Claude.ai and click "Projects" in the sidebar, then "Create project".
2. 2
   Add the SKILL.md as project knowledge. Click "Add content" and paste the full content from the SKILL.md Reference section below. Alternatively, save it as a .md file and upload it.
3. 3
   Set the custom instructions for the project. Click "Set custom instructions" and paste this:

   You are a Waveboard assistant. Use the Waveboard API documentation in your project knowledge to help me manage my projects, tasks, time entries, and invoices.
   
   API Base URL: https://waveboard.pipewave.de/api/v1
   API Key: sk_live_YOUR_KEY_HERE
   
   When I ask you to do something, show me the exact curl command you would run, then explain what it does. Always use the Authorization header with the Bearer token.

   Replace sk_live_YOUR_KEY_HERE with your actual API key.

4. 4
   Start chatting! Open a new conversation in the project and ask Claude to manage your Waveboard.

Option 1: Custom GPT with Actions (Full Integration)

Custom GPTs can directly call the Waveboard API. ChatGPT will execute the API calls for you and show the results. This requires a ChatGPT Plus subscription.

1. 1
   Go to ChatGPT → Explore GPTs → Create.
2. 2
   In the Configure tab, give it a name (e.g. "Waveboard Assistant") and set instructions like: "You help me manage my Waveboard projects, tasks, and time entries."
3. 3
   Under Knowledge, upload the SKILL.md file (copy from below and save as a .md file).
4. 4
   Scroll to Actions, click "Create new action", and paste the OpenAPI schema below. Then click the gear icon next to Authentication, select "API Key", set Auth Type to Bearer, and paste your Waveboard API key.
5. 5
   Save and start using your GPT!

Option 2: Simple Knowledge Upload

If you don't need direct API execution, you can just upload the SKILL.md as Knowledge to your Custom GPT. ChatGPT will then know all the API endpoints and can show you the exact curl commands to run yourself. No Actions configuration needed.

The simplest approach works with any AI tool (Gemini, Copilot, local LLMs, etc.): just copy the SKILL.md content from below and paste it into your conversation. The AI will then know all available endpoints and can help you construct API calls.

This is the full content of the SKILL.md file. Click the copy button in the top-right corner to copy everything, then paste it wherever you need it (Claude Project knowledge, ChatGPT GPT knowledge, or directly into a conversation).

---
name: waveboard
description: Manage tasks, projects, clients, time entries, invoices, contacts, and more in Waveboard — a freelancer project management tool.
requires:
  env:
    - WAVEBOARD_API_KEY
    - WAVEBOARD_URL
---

# Waveboard

Waveboard is a freelancer project management tool with clients, projects, kanban task boards, time tracking, invoicing, contacts, and team management.

Use this skill to look up, create, and update tasks, browse projects and clients, log time entries, manage invoices, track contacts, and plan your day with the Today board.

## Authentication

All requests need the API key in the Authorization header:

\`\`\`
Authorization: Bearer $WAVEBOARD_API_KEY
\`\`\`

The base URL is \`$WAVEBOARD_URL\`.

## Response Format

Responses always follow this structure:

\`\`\`json
// Single item
{ "data": { ... } }

// List
{ "data": [...], "meta": { "total": 42 } }

// Error
{ "error": { "code": "NOT_FOUND", "message": "Task not found" } }
\`\`\`

Lists support pagination with \`?limit=\` (default 50, max 100) and \`?offset=\` query params.

## Endpoints

### Clients
- GET /api/v1/clients — List clients (?search=name)
- GET /api/v1/clients/:id — Get client
- POST /api/v1/clients — Create client (name required)
- PUT /api/v1/clients/:id — Update client
- DELETE /api/v1/clients/:id — Delete client

### Contacts
- GET /api/v1/contacts — List contacts (?client_id=, ?search=)
- GET /api/v1/contacts/:id — Get contact
- POST /api/v1/contacts — Create contact (client_id, first_name required)
- PATCH /api/v1/contacts/:id — Update contact
- DELETE /api/v1/contacts/:id — Delete contact

### Projects
- GET /api/v1/projects — List projects (?client_id=, ?status=)
- GET /api/v1/projects/:id — Get project (includes board_columns)
- POST /api/v1/projects — Create project (name, client_id required)
- PUT /api/v1/projects/:id — Update project
- DELETE /api/v1/projects/:id — Delete project

### Board Columns
- GET /api/v1/projects/:id/columns — List columns
- POST /api/v1/projects/:id/columns — Create column (name, column_type required)
- PATCH /api/v1/projects/:id/columns/:colId — Update column
- DELETE /api/v1/projects/:id/columns/:colId — Delete column

### Labels
- GET /api/v1/projects/:id/labels — List labels
- POST /api/v1/projects/:id/labels — Create label (name required)
- PATCH /api/v1/projects/:id/labels/:labelId — Update label
- DELETE /api/v1/projects/:id/labels/:labelId — Delete label

### Modules
- GET /api/v1/projects/:id/modules — List modules
- POST /api/v1/projects/:id/modules — Create module (name required)
- PATCH /api/v1/projects/:id/modules/:modId — Update module
- DELETE /api/v1/projects/:id/modules/:modId — Delete module

### Tasks
- GET /api/v1/tasks — List tasks (?project_id=, ?column_type=, ?priority=, ?search=)
- GET /api/v1/tasks/:id — Get task (includes labels, module, project, column)
- POST /api/v1/tasks — Create task (project_id, column_id, title required)
- PATCH /api/v1/tasks/:id — Update task
- DELETE /api/v1/tasks/:id — Delete task

### Task Comments
- GET /api/v1/tasks/:id/comments — List comments
- POST /api/v1/tasks/:id/comments — Create comment (content required)
- PATCH /api/v1/tasks/:id/comments/:commentId — Update comment
- DELETE /api/v1/tasks/:id/comments/:commentId — Delete comment

### Task Labels
- GET /api/v1/tasks/:id/labels — Get assigned labels
- POST /api/v1/tasks/:id/labels — Assign label (label_id required)
- DELETE /api/v1/tasks/:id/labels/:labelId — Remove label

### Time Entries
- GET /api/v1/time-entries — List entries (?project_id=, ?task_id=, ?from=, ?to=)
- GET /api/v1/time-entries/:id — Get entry
- POST /api/v1/time-entries — Create entry (project_id required)
- PATCH /api/v1/time-entries/:id — Update entry
- DELETE /api/v1/time-entries/:id — Delete entry

### Timer
- GET /api/v1/time-entries/running — Get running timer
- POST /api/v1/time-entries/running — Start timer (project_id required, auto-stops previous)
- POST /api/v1/time-entries/:id/stop — Stop timer

### Invoices
- GET /api/v1/invoices — List invoices (?client_id=, ?status=)
- GET /api/v1/invoices/:id — Get invoice (includes items)
- POST /api/v1/invoices — Create invoice (client_id required, items: [{description, quantity, unit_price}])
- PATCH /api/v1/invoices/:id — Update invoice
- DELETE /api/v1/invoices/:id — Delete invoice (draft only)

### Today Board
- GET /api/v1/today — Get today's tasks (?date=YYYY-MM-DD)
- POST /api/v1/today — Add task to today (task_id required)
- DELETE /api/v1/today/:taskId — Remove from today

### Company Profile
- GET /api/v1/company-profile — Get profile
- PUT /api/v1/company-profile — Create/update profile (upsert)

## Common Workflows

### Create a task: GET project -> find column_id -> POST /tasks
### Log time: POST /time-entries with project_id, task_id, duration_seconds
### Start timer: POST /time-entries/running -> later POST /time-entries/:id/stop
### Create invoice: POST /invoices with client_id and items array
### Move task to done: GET project columns -> find done column -> PATCH /tasks/:id with column_id