harmonica-mcp

Harmonica MCP Server


MCP server enabling AI agents to create and query Harmonica deliberation sessions.

Harmonica is a structured deliberation platform where groups coordinate through AI-facilitated async conversations. Create a session with a topic and goal, share a link with participants, and each person has a private 1:1 conversation with an AI facilitator. Responses are synthesized into actionable insights. Learn more.

Quick Start

1. Get an API key

1. Sign up for Harmonica (free)
2. Go to Profile > API Keys > Generate API Key
3. Copy your hm_live_... key — it's only shown once

2. Configure your MCP client

Add to your MCP client config (e.g. Claude Code, Cursor, Windsurf):

{
  "mcpServers": {
    "harmonica": {
      "command": "npx",
      "args": ["-y", "harmonica-mcp"],
      "env": {
        "HARMONICA_API_KEY": "hm_live_your_key_here"
      }
    }
  }
}

3. Start a deliberation

Ask your AI agent to create a session:

Create a Harmonica session about "Team Retrospective" with the goal "Review Q1 and identify improvements"

Share the join URL with participants. Once they've responded, use get_responses and get_summary to see the results.

Tools

| Tool | Description | |------|-------------| | create_session | Create a new deliberation session and get a shareable join URL (optional: questions, project_id to file it under a project) | | update_session | Update session metadata (topic, goal, context, critical, prompt; project_id to move it into a project or null to detach) | | list_sessions | List your deliberation sessions (filter by status, search) | | get_session | Get full session details (includes facilitation prompt) | | get_questions | Get pre-session questions (data collection form) | | get_responses | Get participant responses | | get_summary | Get AI-generated summary | | search_sessions | Search by topic or goal | | list_telegram_groups | List Telegram groups registered to the user's account (no parameters) | | install_method_spec | Install an OFL method spec (method.md) as a runnable chain template | | create_project | Create a project (workspace) to group related sessions | | list_projects | List the projects (workspaces) you have access to | | get_project | Get a project by id, with the ids of its linked sessions | | update_project | Rename a project or update its description (editor access) | | delete_project | Soft-delete a project; its sessions are left intact (owner access) | | publish_sensemaking_topic | Publish a project as a public sensemaking topic (/explore + /t/[slug]) |

From Source

git clone https://github.com/harmonicabot/harmonica-mcp.git
cd harmonica-mcp
npm install && npm run build

Then use node /path/to/harmonica-mcp/dist/index.js instead of npx -y harmonica-mcp in your config.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | HARMONICA_API_KEY | Yes | — | Your Harmonica API key | | HARMONICA_API_URL | No | https://app.harmonica.chat | API base URL |

Roadmap

• [ ] One-command install via npx add-mcp (auto-detects Claude Code, Cursor, Windsurf)
• [ ] HTTP transport — zero-install setup, just add a URL
• [ ] Inbound context — feed external data into sessions via MCP
• [ ] Session templates discovery tool
• [ ] TypeScript and Python client SDKs

See Also

• harmonica-chat — Conversational Harmonica companion for Claude Code — design, create, and manage sessions (/harmonica-chat)
• Harmonica docs — Full platform documentation and API reference

License

MIT