# Harmonica MCP Server

[![npm version](https://img.shields.io/npm/v/harmonica-mcp)](https://www.npmjs.com/package/harmonica-mcp)

MCP server enabling AI agents to create and query [Harmonica](https://harmonica.chat) deliberation sessions.

[Harmonica](https://harmonica.chat) 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](https://help.harmonica.chat).

## Quick Start

### 1. Get an API key

1. [Sign up for Harmonica](https://app.harmonica.chat) (free)
2. Go to [Profile](https://app.harmonica.chat/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):

```json
{
  "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) |
| `close_session` | End a session without deleting its participant threads, messages, summaries, or other data |
| `reopen_session` | Reopen a completed session so participants can join again |
| `list_sessions` | Paginate session metadata with optional status/search filters; `platform` scope requires a separately authorized global-admin audit key |
| `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 |
| `list_meetings` | List owned calendar meetings with compact transcript currentness and processing metadata |
| `get_transcript` | Get one bounded transcript page in `turns` or `text` format, with an optional continuation cursor |
| `get_meeting_restrictions` | Get effective processing restrictions, pending candidates, and history for an owned meeting |
| `update_meeting_restrictions` | Set restrictions or review a pending transcript-derived candidate for an owned meeting |
| `update_project` | Rename a project or update its description (editor access) |
| `delete_project` | Soft-delete a project; its sessions are left intact (owner access) |
| `create_unconference_topic` | Create a draft topic in an Unconference project and mirror it to the connected brain repository (editor access) |
| `publish_sensemaking_topic` | Publish a project as a public sensemaking topic (`/explore` + `/t/[slug]`) |

`get_transcript` returns one page only: 100 segments and 25,000 transcript
characters by default, with hard maxima of 200 segments and 50,000 characters.
Pass `pagination.next_cursor` back as `cursor` to continue. Complete transcript
download is owner-only through REST and is intentionally not an MCP tool.

## From Source

```bash
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](https://github.com/harmonicabot/harmonica-chat)** — Conversational Harmonica companion for Claude Code — design, create, and manage sessions (`/harmonica-chat`)
- **[Harmonica docs](https://help.harmonica.chat)** — Full platform documentation and API reference

## License

MIT