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, 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 |

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