Aha.io — Claude Code MCP server: ideas, epics, releases
Wires Aha.io into your coding agent so it can search, read and update ideas, features, epics, releases, goals and comments.
claude mcp add aha-mcp -e AHA_COMPANY=<AHA_COMPANY> -e AHA_TOKEN=<AHA_TOKEN> -- npx -y @cedricziel/aha-mcpWhat Aha.io 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.
What it helps with
- 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 for the agent
- 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
How to install Aha.io
Platform CLI
claude mcp add aha-mcp -e AHA_COMPANY=<AHA_COMPANY> -e AHA_TOKEN=<AHA_TOKEN> -- npx -y @cedricziel/aha-mcpReplace <…> with your own values
Platform CLI
codex mcp add ahaio --env AHA_COMPANY=<AHA_COMPANY> --env AHA_TOKEN=<AHA_TOKEN> -- npx -y @cedricziel/aha-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"ahaio": {
"command": "npx",
"args": [
"-y",
"@cedricziel/aha-mcp"
],
"env": {
"AHA_COMPANY": "<AHA_COMPANY>",
"AHA_TOKEN": "<AHA_TOKEN>"
}
}
}
}Replace <…> with your own values
Config file
{
"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
Platform CLI
gemini mcp add -e AHA_COMPANY=<AHA_COMPANY> -e AHA_TOKEN=<AHA_TOKEN> ahaio npx -y @cedricziel/aha-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Aha.io
How do I install the Aha.io MCP server in Claude Code?
Run claude mcp add aha-mcp -e AHA_COMPANY=<AHA_COMPANY> -e AHA_TOKEN=<AHA_TOKEN> -- npx -y @cedricziel/aha-mcp. Swap the placeholders for your Aha.io subdomain and API token.
What does the Aha.io MCP server do?
It lets an agent search, read and update ideas, features, epics, releases, goals and comments in Aha.io. Queries hit the live API or a local SQLite database that the server syncs in the background.
What does the server need to run?
An Aha.io subdomain in AHA_COMPANY and an API token in AHA_TOKEN. An OAuth token in AHA_ACCESS_TOKEN is an alternative to the API token. Remote access uses the streamable-http mode.
