harmony-mcp
Advanced tools
MCP server for Harmony Kanban board - enables AI coding agents to manage your boards
MCP (Model Context Protocol) server for Harmony. Enables AI coding agents (Claude Code, OpenAI Codex, Cursor, Windsurf) to interact with your Harmony boards.
npx harmony-mcp setup
The smart setup wizard will:
That's it! You're ready to use Harmony with your AI agent.
Connect any MCP-compatible agent to Harmony's hosted endpoint - no local server required.
Endpoint: https://mcp.gethmy.com/mcp
Transport: Streamable HTTP (MCP SDK standard)
Authentication: Bearer token using your hmy_ API key
add-mcpThe fastest way to connect any agent to the remote endpoint. One command configures Claude Code, Cursor, VS Code, Windsurf, Codex, and more:
npx add-mcp https://mcp.gethmy.com/mcp -- --header "Authorization: Bearer hmy_your_key_here"
Useful flags:
| Flag | Description |
|---|---|
-g | Install globally (not scoped to a project) |
-a <agent> | Target specific agents (e.g., -a cursor -a claude-code) |
-y | Skip interactive prompts |
Examples:
# Install for all detected agents
npx add-mcp https://mcp.gethmy.com/mcp -- --header "Authorization: Bearer hmy_your_key_here"
# Install globally for Cursor and Claude Code only
npx add-mcp https://mcp.gethmy.com/mcp -g -a cursor -a claude-code -- --header "Authorization: Bearer hmy_your_key_here"
# Non-interactive (CI-friendly)
npx add-mcp https://mcp.gethmy.com/mcp -y -- --header "Authorization: Bearer hmy_your_key_here"
If you prefer to configure manually (e.g., in Claude.ai's UI):
https://mcp.gethmy.com/mcpBearer hmy_your_key_hereSession management is automatic - sessions have a 1-hour TTL and are created/renewed transparently.
When to use remote vs local: The remote endpoint (via
add-mcpor manual config) works with any MCP-compatible agent and requires no local server. Use the local server (npx harmony-mcp setup) when you need skills, local project context, or memory sync to local markdown files.
Just run setup again in the new project directory:
cd my-new-project
npx harmony-mcp setup
It detects your existing configuration and only asks for the project context.
# Setup (recommended)
npx harmony-mcp setup # Smart setup wizard
# Setup with flags (non-interactive)
npx harmony-mcp setup --api-key KEY --global --workspace ID --project ID
# Status and management
npx harmony-mcp status # Show current configuration
npx harmony-mcp reset # Clear all configuration
# Server (called by agents automatically)
npx harmony-mcp serve # Start MCP server
| Flag | Description |
|---|---|
-k, --api-key <key> | API key (skips prompt) |
-e, --email <email> | Your email for auto-assignment |
-a, --agents <agents...> | Agents to configure: claude, codex, cursor, windsurf |
-g, --global | Install skills globally (recommended) |
-l, --local | Install skills locally in project directory |
-w, --workspace <id> | Set workspace context |
-p, --project <id> | Set project context |
--skip-context | Skip workspace/project selection |
-f, --force | Overwrite existing configuration |
| Agent | Workflow Command | Config Location | Transport |
|---|---|---|---|
| Claude Code | /hmy #42, /hmy-plan | ~/.claude/settings.json | Local (stdio) |
| OpenAI Codex | /prompts:hmy #42 | ~/.codex/config.toml | Local (stdio) |
| Cursor | MCP tools auto-available | .cursor/mcp.json | Local (stdio) |
| Windsurf | MCP tools auto-available | ~/.codeium/windsurf/mcp_config.json | Local (stdio) |
| Claude.ai | MCP tools auto-available | Remote MCP settings in Claude.ai | Remote (HTTP) |
| Any agent | MCP tools auto-available | Auto-configured via npx add-mcp | Remote (HTTP) |
/hmy — Card WorkflowWhen you start working on a card (e.g., /hmy #42):
/hmy-plan — Plan WorkflowA single command for both creating and executing plans. It auto-detects intent based on the argument:
| Argument | Action |
|---|---|
UUID | Fetch and work on existing plan |
#42 | Look up card, then its linked plan |
mobile auth | Search existing plans; if found, work on it; if not, offer to create one |
| (empty) | Start the new plan creation interview |
Creating a plan (/hmy-plan mobile auth):
harmony_create_planExecuting a plan (/hmy-plan <existing plan>):
harmony_create_card - Create a new cardharmony_update_card - Update card propertiesharmony_move_card - Move card to different column (auto-ends agent session on move to done/review)harmony_archive_card - Archive a card (soft-delete, can be restored)harmony_unarchive_card - Restore an archived card back to the boardharmony_delete_card - Delete a cardharmony_assign_card - Assign to team memberharmony_search_cards - Search by title/descriptionharmony_get_card - Get card details by UUIDharmony_get_card_by_short_id - Get card by short ID (e.g., #42)harmony_add_link_to_card - Create a link between two cardsharmony_remove_link_from_card - Remove a link between cardsharmony_get_card_links - Get all links for a cardLink 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 |
harmony_create_column - Create new columnharmony_update_column - Update column propertiesharmony_delete_column - Delete columnharmony_create_label - Create new labelharmony_add_label_to_card - Add label to cardharmony_remove_label_from_card - Remove labelharmony_create_subtask - Create subtaskharmony_toggle_subtask - Toggle completionharmony_delete_subtask - Delete subtaskharmony_list_workspaces - List workspacesharmony_list_projects - List projectsharmony_get_board - Get board state (supports pagination via limit/offset, summary mode, columnId filter, includeArchived)harmony_get_workspace_members - Get team membersharmony_set_workspace_context - Set active workspaceharmony_set_project_context - Set active projectharmony_get_context - Get current contextharmony_process_command - Process natural language commandsharmony_start_agent_session - Start tracking work on a card (with moveToColumn and addLabels side effects)harmony_update_agent_progress - Update progress, status, blockersharmony_end_agent_session - End session (completed/paused); triggers active learning extractionharmony_get_agent_session - Get current session stateharmony_get_agent_profile - Get aggregate performance profile for an agentSessions are automatically started when agents call card-mutating tools without an explicit harmony_start_agent_session. This ensures work is always tracked, even when agents don't explicitly manage sessions.
Trigger tools: harmony_generate_prompt, harmony_update_card, harmony_move_card, harmony_create_subtask, harmony_toggle_subtask, harmony_add_label_to_card, harmony_remove_label_from_card
Behavior:
harmony_start_agent_session) are never auto-endedharmony_generate_prompt - Generate an AI-ready prompt from a card with assembled memory contextParameters:
| 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 |
The prompt builder automatically infers the agent role based on card labels (bug, feature, design, etc.) and injects relevant memory context using the context assembly engine.
Store and retrieve persistent knowledge across sessions. Memories have types, tiers, scopes, confidence scores, and can be linked via typed relations.
CRUD:
harmony_remember - Store a memory entity (markdown with YAML frontmatter)harmony_recall - Retrieve memories by type, tags, scope, or text queryharmony_update_memory - Update an existing memory entityharmony_forget - Archive or delete a memory entityharmony_memory_search - Full-text search across the knowledge baseharmony_relate - Create a typed relationship between two memory entitiesEntity Types: agent, task, decision, context, pattern, error, solution, preference, relationship, commitment, lesson, project, handoff, procedure
Memory Tiers: draft (working notes) → episode (session summaries) → reference (durable knowledge)
Scopes: private, project, workspace, global
Relation Types: learned_from, resolved_by, contradicts, supports, depends_on, part_of, caused_by, relates_to
harmony_vault_index - Compact index of all memory entities (markdown table)harmony_resolve_links - Batch-scan for [[wiki-links]] and auto-create relationsharmony_sync - Bidirectional sync between local markdown files (~/.harmony/memory/) and remote database (directions: pull, push, full)harmony_promote_memory - Promote entity tier: draft → episode or episode → referenceharmony_prune_draft - Remove stale draft memories (dry-run mode by default)harmony_consolidate_memories - Cluster similar draft/episode memories and merge into reference entities (dry-run by default)harmony_backfill_embeddings - Generate vector embeddings for entities missing themharmony_backfill_relations - Retroactively create semantic relations across existing entitiesharmony_get_context_manifest - Debug what memories were loaded/excluded in a prompt assemblyharmony_debug_context - Explain why a specific memory was or wasn't included (relevance score breakdown)harmony_export_memory_graph - Export knowledge graph as DOT format for Graphviz visualizationCreate and manage project plans with a phased workflow: plan → execute → verify → done.
harmony_list_plans - List plans in a project (filter by status or workflow phase)harmony_create_plan - Create a new plan with embedded tasksharmony_get_plan - Get plan by ID or card IDharmony_update_plan - Update plan title, content, status, or phaseharmony_advance_plan - Advance to next phase with side effects:
harmony_onboard - Complete end-to-end onboarding: signup → workspace → project → API keyharmony_signup - Create a new user accountharmony_create_workspace - Create a new workspaceharmony_create_project - Create a new project with template columns (kanban, scrum, or simple)harmony_send_invitations - Send workspace invitations to team membersharmony_generate_api_key - Generate an API key for the authenticated userYou can also call the Harmony API directly from any HTTP client:
curl -X GET "https://gethmy.com/api/v1/workspaces" \
-H "X-API-Key: hmy_your_key_here"
| Endpoint | Method | Description |
|---|---|---|
/v1/workspaces | GET | List workspaces |
/v1/workspaces/:id/projects | GET | List projects in workspace |
/v1/workspaces/:id/members | GET | Get workspace members |
/v1/board/:projectId | GET | Get full board state |
/v1/cards | POST | Create card |
/v1/cards/:id | GET | Get card |
/v1/cards/:id | PATCH | Update card |
/v1/cards/:id | DELETE | Delete card |
/v1/cards/:id/move | POST | Move card |
/v1/cards/:id/prompt | GET | Generate prompt from card |
/v1/cards/:id/links | GET | Get card links |
/v1/cards/:id/links | POST | Create card link |
/v1/cards/:id/labels | POST | Add label to card |
/v1/cards/:id/labels/:labelId | DELETE | Remove label |
/v1/search?q=query | GET | Search cards |
/v1/columns | POST | Create column |
/v1/columns/:id | PATCH | Update column |
/v1/columns/:id | DELETE | Delete column |
/v1/labels | POST | Create label |
/v1/subtasks | POST | Create subtask |
/v1/subtasks/:id/toggle | POST | Toggle subtask |
/v1/subtasks/:id | DELETE | Delete subtask |
/v1/links/:id | DELETE | Delete card link |
/v1/nlu | POST | Process natural language |
Stored in ~/.harmony-mcp/config.json:
{
"apiKey": "hmy_...",
"apiUrl": "https://gethmy.com/api",
"userEmail": "you@example.com",
"activeWorkspaceId": null,
"activeProjectId": null
}
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.
When your email is configured during setup, 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 update your email:
npx harmony-mcp setup --email you@example.com
The email must match your Harmony account email to work correctly.
npx harmony-mcp status
Example output:
Status: Configured
API:
Key: hmy_abc1...
URL: https://gethmy.com/api
Email: y***@example.com
Skills:
Installed: Yes (global)
~/.agents/skills/hmy/SKILL.md
Context:
Local config: .harmony-mcp.json
Workspace: my-team-id
Project: my-project-id
Global config: ~/.harmony-mcp/config.json
Workspace: (not set)
Project: (not set)
Active (effective):
Workspace: my-team-id ← local
Project: my-project-id ← local
Add this to prevent accidentally committing local config:
.harmony-mcp.json
┌─────────────────┐ MCP Protocol ┌──────────────────┐
│ Claude Code │ ───────────────────────▶│ harmony-mcp │
│ Cursor │ (local stdio) │ (local server) │
│ Windsurf │ └────────┬─────────┘
│ Codex │ │
└─────────────────┘ │ API Key Auth
▼
┌─────────────────┐ Streamable HTTP ┌──────────────────┐
│ Claude.ai │ ───────────────────────▶│ Remote MCP │
│ Any MCP client │ (Bearer: hmy_xxx) │ mcp.gethmy.com │──┐
└─────────────────┘ └──────────────────┘ │
│
┌─────────────┘
▼
┌──────────────────┐
│ Harmony API │
│ (Edge Function) │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Database │
│ (Supabase) │
└──────────────────┘
Key Benefits:
FAQs
MCP server for Harmony Kanban board - enables AI coding agents to manage your boards
The npm package harmony-mcp receives a total of 63 weekly downloads. As such, harmony-mcp popularity was classified as not popular.
We found that harmony-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.