aha-mcp 1.4.4

Model Context Protocol (MCP) server for the Aha! product management API

fpcm-aha-mcp

Model Context Protocol (MCP) server for the Aha! product management API. Lets AI assistants read and write ideas, features, epics, releases, initiatives, products, pages (notes), record links, comments, and custom-field metadata directly in your Aha! workspace.

Runtimes: the published npm package is Node.js 18+ (TypeScript compiled to dist/). This repository also ships a Python server (aha_mcp) with the same tool surface — use either one. See SETUP.md for Node vs Python and local clone paths.

Quick start

npx -y fpcm-aha-mcp

Or install globally:

npm install -g fpcm-aha-mcp

Configuration

The server reads credentials from environment variables (pass them via your MCP client config or a .env file in the working directory):

Variable	Required	Description
AHA_ACCOUNT_DOMAIN	Yes	Your Aha! subdomain — the part before .aha.io (e.g. mycompany)
AHA_API_KEY	Yes	Your Aha! API key — Aha! → Settings → Account → API
AHA_PRODUCT_ID	No	Default product ID used when product_id is omitted from a tool call

Getting your API key: log in to Aha!, go to Settings → Account → API, and generate or copy your key.

Available tools

Products

Tool	Description
list_products	List all products (workspaces) in the account
get_product	Get a specific product by ID or reference prefix

Ideas

Tool	Description
search_ideas	Search ideas in a product, with optional filters for release, epic, initiative, or workflow status. Supports fuzzy name matching. Optional sort: recent, trending, or popular (for “top voted” style lists, combine with fields such as endorsements_count). Pass-through filters: created_since, created_before, updated_since, tag, user_id, idea_user_id. limit is per page and capped at 200 (Aha! maximum).
get_idea	Get a specific idea by ID or reference number (e.g. PRJ1-I-1)
create_idea	Create a new idea in a product
update_idea	Update an existing idea

Comments

Tool	Description
list_comments	List internal (workspace) comments on a record. record_type: idea, feature, epic, requirement, initiative, goal, release, release_phase, page, or task. Not portal comments.
create_comment	Create an internal comment (API key user). Optional parent_comment_id for a reply to a top-level comment. Does not create portal comments.
list_idea_portal_comments	List portal/client comments on an idea. Use list_comments with record_type=idea for internal threads.

Features

Tool	Description
search_features	Search features in a product, with optional filters for release, epic, or initiative. Supports fuzzy name matching.
get_feature	Get a specific feature by ID or reference number (e.g. PRJ1-1)
create_feature	Create a new feature in a release; optional release_phase (phase id or exact phase name on that release)
update_feature	Update an existing feature; optional release_phase to move the feature to a phase or milestone

Epics

Tool	Description
search_epics	Search epics in a product or release
get_epic	Get a specific epic by ID or reference number (e.g. PRJ1-E-1)
create_epic	Create a new epic in a release or product
update_epic	Update an existing epic

Releases

Tool	Description
search_releases	Search releases in a product
get_release	Get a specific release by ID or reference number (e.g. PRJ1-R-1)
create_release	Create a new release in a product
update_release	Update an existing release

Release phases (schedule)

Phases and milestones on a release’s roadmap / Gantt.

Tool	Description
list_release_phases	List phases and milestones for a release (optional filter: phase vs milestone)
get_release_phase	Get one phase or milestone by id
create_release_phase	Create a phase or milestone on a release
update_release_phase	Update a phase or milestone (partial updates)
delete_release_phase	Delete a phase or milestone

Initiatives

Tool	Description
list_initiatives	List initiatives in a product
get_initiative	Get a specific initiative by ID or reference number (e.g. PRJ1-S-1)

Custom fields and layout

Tool	Description
list_custom_field_definitions	List account-wide custom field definitions (optional filters; paginate for full scans)
list_custom_field_options	List allowed values for a picklist-style custom field
get_custom_layout_for_product_record	Get the custom layout / fields for a record type in a product
export_product_seed_bundle	Export a structured seed bundle for a product (for backups or migrations)
invalidate_metadata_cache	Clear the server-side metadata cache after Aha! configuration changes

Pages (Notes)

In the Aha! REST API, workspace Notes are pages.

Tool	Description
list_pages	List or search pages for a product
get_page	Get one page by id or reference key
create_page	Create a page under a product
update_page	Update a page (partial updates supported)
delete_page	Delete a page

Record links

Tool	Description
list_page_record_links	List links attached to a page (optionally include parent/child direction)
create_page_record_link	Link a page to another record (feature, idea, epic, release, etc.) with an Aha! link_type
delete_record_link	Remove a link by its record link id (from list_page_record_links), not by page or feature id

Setup guide

See SETUP.md for step-by-step instructions to add this MCP server to Claude Desktop or Claude Code.

Developing from a clone

• Node: npm install and npm run build (required before npm start or pointing MCP at dist/index.js).
• Python: install the package in editable mode (pip install -e . from the repo root), then run python -m aha_mcp (or the aha-mcp console script). Dependencies are listed in pyproject.toml.
• Tests: python -m unittest discover -s tests -p "test_*.py" covers shared API behavior (e.g. idea search query parameters). scripts/verify_step0_popular_sort.py is an optional live check against your Aha! account (AHA_API_KEY, AHA_ACCOUNT_DOMAIN) to sanity-check sort=popular ordering.

Publishing

Releases are published to npmjs.com/package/fpcm-aha-mcp via GitHub Actions on every v* tag push using OIDC Trusted Publishing — no token secrets required. The published version is always the version field in package.json (keep it in sync with the tag, e.g. 1.4.3 → tag v1.4.3). To publish a new version:

# bump version in package.json and package-lock.json (root), then:
git tag v1.4.3
git push origin main --tags