harmony-mcp

MCP (Model Context Protocol) server for Harmony Kanban board. Enables AI coding agents (Claude Code, OpenAI Codex, Cursor, Windsurf) to interact with your Harmony boards.

Features

• 29 MCP Tools for full board control (cards, columns, labels, subtasks, links)
• Card Linking - create relationships between cards (blocks, relates_to, duplicates, is_part_of)
• Prompt Builder - generate AI-ready prompts from cards with context
• Agent Session Tracking - track work progress with timer badges
• Auto-Assignment - automatically assign cards to you when starting agent sessions
• Multi-Agent Support - works with Claude Code, Codex, Cursor, Windsurf
• One-Command Setup - auto-configure all supported agents
• Natural Language Processing via voice-nlu edge function
• API Key Authentication - no database credentials required

Quick Start

1. Install

npm install -g harmony-mcp

2. Generate an API Key

1. Log into Harmony
2. Go to Settings → API Keys
3. Click "Generate New Key"
4. Copy the key (it starts with hmy_)

3. Configure

harmony-mcp configure --api-key hmy_your_key_here

# Optional: Set your email for auto-assignment
harmony-mcp configure --api-key hmy_your_key_here --user-email [email protected]

4. Initialize for Your AI Agents

# Auto-detect and configure all installed agents
harmony-mcp init --detect

# Or configure all supported agents
harmony-mcp init --all

# Or configure specific agents
harmony-mcp init --agent claude codex cursor windsurf

This creates the necessary configuration files and workflow prompts for each agent.

Manual Setup (Alternative)

If you prefer manual setup for Claude Code:

claude mcp add harmony -- harmony-mcp serve

Or add to ~/.claude/settings.json:

{
  "mcpServers": {
    "harmony": {
      "command": "harmony-mcp",
      "args": ["serve"]
    }
  }
}

Supported AI Agents

| Agent | MCP Config | Workflow Command | | ---------------- | ------------------------------------- | ------------------------ | | Claude Code | ~/.claude/settings.json | /hmy #42 | | OpenAI Codex | ~/.codex/config.toml | /prompts:hmy #42 | | Cursor | .cursor/mcp.json | MCP tools auto-available | | Windsurf | ~/.codeium/windsurf/mcp_config.json | MCP tools auto-available |

Card Workflow

When you start working on a card (e.g., /hmy #42):

1. Find - Locates the card by short ID, UUID, or name
2. Move - Moves the card to "In Progress" column
3. Label - Adds the "agent" label to indicate AI is working
4. Assign - Auto-assigns the card to you (if userEmail is configured)
5. Track - Starts a session timer visible in the UI
6. Implement - Work on the task with progress updates
7. Complete - Move to "Review" when done

CLI Commands

harmony-mcp configure                 # Set up API key (interactive)
harmony-mcp configure -k KEY -e EMAIL # Set up with API key and email
harmony-mcp init                      # Initialize for AI agents (interactive)
harmony-mcp init --all                # Configure all supported agents
harmony-mcp init --detect             # Auto-detect and configure installed agents
harmony-mcp init --agent X Y          # Configure specific agents
harmony-mcp init -w WS -p PROJ        # Initialize with local workspace/project context
harmony-mcp status                    # Show current config (global and local)
harmony-mcp reset                     # Clear configuration
harmony-mcp set-workspace ID          # Set active workspace (global)
harmony-mcp set-workspace ID -l       # Set active workspace (local project)
harmony-mcp set-project ID            # Set active project (global)
harmony-mcp set-project ID -l         # Set active project (local project)
harmony-mcp set-user-email EMAIL      # Set email for auto-assignment
harmony-mcp clear-user-email          # Disable auto-assignment
harmony-mcp serve                     # Start MCP server

Available Tools

Card Operations

• harmony_create_card - Create a new card
• harmony_update_card - Update card properties
• harmony_move_card - Move card to different column
• harmony_delete_card - Delete a card
• harmony_assign_card - Assign to team member
• harmony_search_cards - Search by title/description
• harmony_get_card - Get card details by UUID
• harmony_get_card_by_short_id - Get card by short ID (e.g., #42)

Card Link Operations

• harmony_add_link_to_card - Create a link between two cards
• harmony_remove_link_from_card - Remove a link between cards
• harmony_get_card_links - Get all links for a card

Link Types: | Type | Description | |------|-------------| | relates_to | Generic relationship between cards | | blocks | Source card blocks target card | | duplicates | Source card duplicates target card | | is_part_of | Source card is part of target card |

Column Operations

• harmony_create_column - Create new column
• harmony_update_column - Update column properties
• harmony_delete_column - Delete column

Label Operations

• harmony_create_label - Create new label
• harmony_add_label_to_card - Add label to card
• harmony_remove_label_from_card - Remove label

Subtask Operations

• harmony_create_subtask - Create subtask
• harmony_toggle_subtask - Toggle completion
• harmony_delete_subtask - Delete subtask

Context Operations

• harmony_list_workspaces - List workspaces
• harmony_list_projects - List projects
• harmony_get_board - Get full board state
• harmony_get_workspace_members - Get team members
• harmony_set_workspace_context - Set active workspace
• harmony_set_project_context - Set active project
• harmony_get_context - Get current context

Natural Language

• harmony_process_command - Process natural language commands

Agent Session Tracking

• harmony_start_agent_session - Start tracking work on a card
• harmony_update_agent_progress - Update progress, status, blockers
• harmony_end_agent_session - End session (completed/paused)
• harmony_get_agent_session - Get current session state

Prompt Generation

• harmony_generate_prompt - Generate an AI-ready prompt from a card

Parameters: | Parameter | Description | |-----------|-------------| | cardId | Card UUID to generate prompt from | | shortId | Alternative: Card short ID (e.g., 42 for #42) | | variant | analysis (understand/plan), draft (design solution), execute (implement fully) | | includeDescription | Include card description (default: true) | | includeSubtasks | Include subtasks in prompt (default: true) | | includeLinks | Include linked cards in prompt (default: true) | | customConstraints | Additional instructions to append |

Variants:

• analysis - Understand the problem and create a plan
• draft - Design a solution approach
• execute - Full implementation (default)

The prompt builder automatically infers the agent role based on card labels (bug, feature, design, etc.) and includes relevant context from linked cards.

Direct API Access

You can also call the Harmony API directly from any HTTP client:

curl -X GET "https://gethmy.com/api/workspaces" \
  -H "X-API-Key: hmy_your_key_here"

API Endpoints

| Endpoint | Method | Description | | ---------------------------- | ------ | -------------------------- | | /workspaces | GET | List workspaces | | /workspaces/:id/projects | GET | List projects in workspace | | /workspaces/:id/members | GET | Get workspace members | | /board/:projectId | GET | Get full board state | | /cards | POST | Create card | | /cards/:id | GET | Get card | | /cards/:id | PATCH | Update card | | /cards/:id | DELETE | Delete card | | /cards/:id/move | POST | Move card | | /search?q=query | GET | Search cards | | /columns | POST | Create column | | /columns/:id | PATCH | Update column | | /columns/:id | DELETE | Delete column | | /labels | POST | Create label | | /cards/:id/labels | POST | Add label to card | | /cards/:id/labels/:labelId | DELETE | Remove label | | /subtasks | POST | Create subtask | | /subtasks/:id/toggle | POST | Toggle subtask | | /subtasks/:id | DELETE | Delete subtask | | /cards/:id/links | GET | Get card links | | /cards/:id/links | POST | Create card link | | /links/:id | DELETE | Delete card link | | /cards/:id/prompt | GET | Generate prompt from card | | /nlu | POST | Process natural language |

Configuration

Global Configuration

Your global configuration is stored in ~/.harmony-mcp/config.json:

{
  "apiKey": "hmy_...",
  "apiUrl": "https://gethmy.com/api",
  "activeWorkspaceId": null,
  "activeProjectId": null,
  "userEmail": "[email protected]"
}

Auto-Assignment

When userEmail is configured, cards are automatically assigned to you when you start an agent session (e.g., via /hmy #42). This helps track who is working on what.

To enable auto-assignment:

harmony-mcp set-user-email [email protected]

To disable auto-assignment:

harmony-mcp clear-user-email

The email must match your Harmony account email to work correctly.

Local Project Configuration

For multi-project workflows, you can set project-specific context using local configuration. This is stored in .harmony-mcp.json in your project root:

{
  "workspaceId": "uuid-here",
  "projectId": "uuid-here"
}

Priority: Local config overrides global config for workspace and project context.

Security: API key is never stored locally (only in global config) to prevent accidental commits.

Setting Local Context

# During initialization
harmony-mcp init --workspace <ws-id> --project <proj-id>

# Or separately
harmony-mcp set-workspace <id> --local
harmony-mcp set-project <id> --local

Viewing Configuration

harmony-mcp status

Example output:

Status: Configured
API Key: hmy_abc1...
API URL: https://gethmy.com/api
User Email: y***@example.com

Global Context:
  Workspace: <global-ws-id>
  Project: <global-proj-id>

Local Context (.harmony-mcp.json):
  Workspace: <local-ws-id>
  Project: <local-proj-id>

Active (effective):
  Workspace: <local-ws-id>  ← local
  Project: <local-proj-id>  ← local

Recommended .gitignore

Add this to prevent accidentally committing local config:

.harmony-mcp.json

Architecture

┌─────────────────┐      MCP Protocol       ┌──────────────────┐
│  Claude Code    │ ───────────────────────▶│  harmony-mcp     │
│  Claude Desktop │                         │  (local server)  │
│  Custom Agents  │                         └────────┬─────────┘
└─────────────────┘                                  │
                                                     │ API Key Auth
                                                     ▼
                                          ┌──────────────────┐
                                          │  Harmony API     │
                                          │  (Edge Function) │
                                          └────────┬─────────┘
                                                   │
                                                   ▼
                                          ┌──────────────────┐
                                          │    Database      │
                                          │    (Supabase)    │
                                          └──────────────────┘

Key Benefits:

• No Database credentials needed - just a Harmony API key
• Any Harmony user can use it
• Business logic stays in Harmony
• Centralized security and rate limiting