# Aha.io

Wires Aha.io into your coding agent so it can search, read and update ideas, features, epics, releases, goals and comments.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6
- Author: cedricziel
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cedricziel/aha-mcp
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/ahaio

## What it does

The server exposes Aha.io product data to an agent. It searches records, reads them and writes changes back. Two paths to the data: live API calls and a local SQLite copy the server keeps in sync in the background. Semantic search runs on vector embeddings, so a query can match an idea by meaning rather than by exact wording.

Startup fails without `AHA_COMPANY` and `AHA_TOKEN` — your Aha.io subdomain and API token. An OAuth token in `AHA_ACCESS_TOKEN` works instead of the API token. The default transport is `stdio`; `streamable-http` on port 3001 covers remote clients, optionally behind a Bearer token. The old `sse` transport is gone, and a config that still asks for it starts anyway on `streamable-http` with a warning.

Settings resolve in a fixed order: environment variables first, then `~/.aha-mcp-config.json`, then defaults. Tool calls are rate limited per minute, 120 by default, and setting it to zero turns the limit off. Local development runs on Bun.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `AHA_COMPANY`, `AHA_TOKEN` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add aha-mcp -e AHA_COMPANY=<AHA_COMPANY> -e AHA_TOKEN=<AHA_TOKEN> -- npx -y @cedricziel/aha-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add ahaio --env AHA_COMPANY=<AHA_COMPANY> --env AHA_TOKEN=<AHA_TOKEN> -- npx -y @cedricziel/aha-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "ahaio": {
            "command": "npx",
            "args": [
                "-y",
                "@cedricziel/aha-mcp"
            ],
            "env": {
                "AHA_COMPANY": "<AHA_COMPANY>",
                "AHA_TOKEN": "<AHA_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "ahaio": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@cedricziel/aha-mcp"
            ],
            "env": {
                "AHA_COMPANY": "<AHA_COMPANY>",
                "AHA_TOKEN": "<AHA_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e AHA_COMPANY=<AHA_COMPANY> -e AHA_TOKEN=<AHA_TOKEN> ahaio npx -y @cedricziel/aha-mcp
```
Replace <…> with your own values

## When to use it
- find an Aha.io idea by meaning instead of exact title
- read an epic together with the records linked to it
- change a record's status or text from the agent chat
- list releases and goals for a product
- comment on an idea without opening the web UI

## Example prompts
- Find every Aha.io idea about report exports and show me their statuses
- List the open epics in the current release with their progress
- Add a comment to the dark mode idea: customers keep asking for it on mobile

## Similar
- [Obsidian Brain](https://affpapa.org/en/nevibecode/mcp/obsidian-brain.md) — MCP server · ★ 14
- [Sugar](https://affpapa.org/en/nevibecode/mcp/sugar.md) — MCP server · ★ 98
- [openchronicle-mcp](https://affpapa.org/en/nevibecode/mcp/openchronicle-mcp.md) — MCP server · ★ 16
- [longhand](https://affpapa.org/en/nevibecode/plugins/longhand.md) — plugin · ★ 14
- [openviking-memory](https://affpapa.org/en/nevibecode/skills/openviking-memory.md) — skill · 504 installs
- [basic-memory](https://affpapa.org/en/nevibecode/mcp/basic-memory.md) — MCP server · ★ 4362

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md