aha-mcp+

The Aha! MCP server, but useful.

A supercharged fork of aha-develop/aha-mcp with 60+ tools covering the full Aha! API — features, ideas, releases, epics, requirements, comments, todos, goals, strategic models, workflows, integrations, and more. Read and write. Built for people who actually want to do things in Aha! from Claude Desktop, not just read a feature title.

┌────────────────────────────────────────────────────────┐
│  Upstream aha-mcp:          3 read-only GraphQL tools  │
│  @dvermagithub/aha-mcp:    60+ tools, full CRUD, REST  │
└────────────────────────────────────────────────────────┘

Why this fork exists

The upstream server is a proof of concept — three GraphQL tools that read a feature, a page, and search. That's it. You can't list your releases, can't see your epics, can't update a status, can't leave a comment, can't even find out who you are.

This fork fixes that.

	Upstream	`@dvermagithub/aha-mcp`
Read features, pages, search	✅	✅
Read releases, epics, ideas, requirements	❌	✅
Read goals, initiatives, strategic models	❌	✅
Read your own assignments & todos	❌	✅
Read workflows, integrations, record links	❌	✅
Create/update/delete features, ideas, comments, todos	❌	✅
Auto-resolve any reference number	❌	✅
Multi-type global search	❌	✅
Delete guardrails	—	✅ `confirm: true` required
Rich GraphQL responses (status, assignee, dates, estimates, tags)	❌	✅

Quick start

1. Get an Aha! API token secure.aha.io/settings/api_keys → Create new API key

2. Add to your MCP client

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "aha-mcp": {
      "command": "npx",
      "args": ["-y", "@dvermagithub/aha-mcp"],
      "env": {
        "AHA_API_TOKEN": "your_token_here",
        "AHA_DOMAIN": "yourcompany"
      }
    }
  }
}

Fully quit Claude Desktop (tray → Quit) and reopen. You're live.

Cursor, Cline, RooCode, VS Code

Same config shape — see AI Tools & Editors below.

What you can do

🔍 Ask questions

"What's the status of DEVELOP-123?"
"Show me active releases for PROD"
"Who's assigned to epics in the next release?"
"Find all ideas mentioning AI from last month"
"What comments are on ADT-123-1?"
"What's on my plate this week?"

✍️ Make changes

"Create a feature called 'Dark mode support' in release DEVELOP-R-5"
"Update DEVELOP-123 — set status to 'In development' and assign it to jane@company.com"
"Add a comment to DEVELOP-123 summarizing our call"
"Create an idea under PROD with a description from this conversation"
"Mark my todo #42 as complete"

🎯 Strategic context

"What are our current goals and key results?"
"Show me the strategic model for Q2"
"Which initiatives are active this quarter?"

Tool reference

📖 Read tools

Core records

Resource	List	Get
Features	`list_features`	`get_feature_rest`, `get_record`
Requirements	`list_requirements`	`get_requirement_rest`, `get_record`
Ideas	`list_ideas`	`get_idea`
Epics	`list_epics`	`get_epic`
Releases	`list_releases`	`get_release`
Release phases	`list_release_phases`	`get_release_phase`
Pages	`list_pages`	`get_page`, `get_page_rest`
Notebooks	`list_notebooks`	—

Strategy

Resource	List	Get
Goals	`list_goals`	`get_goal`
Key results	`list_key_results`	`get_key_result`
Initiatives	`list_initiatives`	`get_initiative`
Strategic models	`list_strategic_models`	`get_strategic_model`

Org & people

Resource	List	Get
Products	`list_products`	`get_product`
Users	`list_users`	`get_user`
Workflows	`list_workflows`	`get_workflow`
Integrations	`list_integrations`	`get_integration`
Competitors	`list_competitors`	`get_competitor`

Activity

Resource	List	Get
Comments	`list_comments`	`get_comment`
Todos	`list_todos`	`get_todo`
Record links	`list_record_links`	`get_record_link`
Idea endorsements	`list_idea_endorsements`	`get_idea_endorsement`
Idea organizations	`list_idea_organizations`	`get_idea_organization`
Custom table records	`list_custom_table_records`	`get_custom_table_record`

✨ Ergonomic tools

resolve_reference — pass any reference (PROD-123, PROD-I-45, PROD-R-1, PROD-E-7, PROD-N-12, PROD-123-1). Auto-detects type, returns the record.
search_global — search across Features, Epics, Ideas, Requirements, and Pages in a single call.
get_me — who the API token belongs to.
list_my_assigned — everything assigned to you.
list_my_pending_tasks — your open todos.

✏️ Write tools

All updates are partial — send only what you want to change. Deletes require confirm: true as a guardrail. Every write tool accepts common fields (name, description, workflow_status, assigned_to_user, tags, start_date, due_date) plus an extra_fields escape hatch for custom fields and specialized attributes.

Resource	Create	Update	Delete
Features	`create_feature`	`update_feature`	`delete_feature`
Requirements	`create_requirement`	`update_requirement`	`delete_requirement`
Ideas	`create_idea`	`update_idea`	`delete_idea`
Comments	`create_comment`	`update_comment`	`delete_comment`
Todos	`create_todo`	`update_todo`	`delete_todo`
Epics	`create_epic`	`update_epic`	`delete_epic`
Releases	`create_release`	`update_release`	`delete_release`
Goals	—	`update_goal`	—
Initiatives	—	`update_initiative`	—

Common filters on every `list_*` tool

query — full-text search
updated_since — ISO 8601 timestamp
tag — filter by tag
assigned_to_user — id or email
page (default 1), per_page (default 30, max 200)
include_custom_fields — set true to include custom fields in the response
fields — comma-separated field list for sparse responses

Nested scopes auto-route to the efficient endpoint. Example: list_features with release_id hits /releases/:id/features, with epic_id hits /epics/:id/features, etc.

Environment variables

Variable	Required	Description
`AHA_API_TOKEN`	✅	Your Aha! API token
`AHA_DOMAIN`	✅	Your Aha! subdomain (e.g. `yourcompany` for `yourcompany.aha.io`)

AI tools & editors

Works with any MCP-compatible client. Config shape is always the same — command: "npx", args: ["-y", "@dvermagithub/aha-mcp"], env vars for auth.

VS Code

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "aha-mcp": {
        "command": "npx",
        "args": ["-y", "@dvermagithub/aha-mcp"]
      }
    }
  }
}

See VS Code MCP docs.

Cursor

Settings → MCP → Add new Global MCP Server:

{
  "mcpServers": {
    "aha-mcp": {
      "command": "npx",
      "args": ["-y", "@dvermagithub/aha-mcp"]
    }
  }
}

Cline

Edit cline_mcp_settings.json via Cline MCP Server settings:

{
  "mcpServers": {
    "aha-mcp": {
      "command": "npx",
      "args": ["-y", "@dvermagithub/aha-mcp"]
    }
  }
}

RooCode

Settings → Edit MCP Settings:

{
  "mcpServers": {
    "aha-mcp": {
      "command": "npx",
      "args": ["-y", "@dvermagithub/aha-mcp"]
    }
  }
}

Use your preferred secure secret management to inject AHA_API_TOKEN and AHA_DOMAIN. Don't hardcode tokens in shared configs.

Development

git clone https://github.com/dvermagithub/aha-mcp.git
cd aha-mcp
npm install
npm run build

Point your MCP client at node /absolute/path/to/aha-mcp/build/index.js while iterating locally.

Architecture

src/
├── index.ts               # MCP server + tool dispatch
├── rest-client.ts         # REST v1 client (GET/POST/PUT/DELETE, 429/404 handling)
├── rest-tools.ts          # REST tool schemas
├── rest-handlers.ts       # REST tool handlers
├── cud-tools.ts           # Create/update/delete tool schemas
├── cud-handlers.ts        # Write handlers with extra_fields merging + confirm guardrail
├── ergonomic-tools.ts     # resolve_reference, search_global
├── handlers.ts            # Original GraphQL handlers
├── queries.ts             # GraphQL queries
└── types.ts               # Shared types & reference regexes

One dispatch pipeline in index.ts: GraphQL tools → ergonomic → CUD → REST. First match wins.

Contributing

PRs welcome. Keep the dispatch order intact and maintain the confirm: true guardrail on any new delete tools.

Design notes

Why both REST and GraphQL? GraphQL gives richer markdown bodies and cross-type search; REST covers way more resources and supports writes cleanly. This server uses whichever fits each operation best.

Why scoped package? To avoid colliding with the upstream aha-mcp on npm and to make it clear this is a personal fork.

Why confirm: true on deletes? Claude Desktop already prompts before every tool call, but a second guardrail at the schema level prevents an accidental approval from wiping a feature.

What's not here?

Strategic roadmaps, milestones, and tags don't have dedicated REST endpoints — skipped. Milestones are modeled as features with feature_type=milestone; filter list_features by type instead. For tags, use the tag filter on any list_* tool.
Admin operations (create user, modify workflow, etc.) — low LLM value, high blast radius.

Troubleshooting

Tools don't show up in Claude Desktop

Fully quit Claude Desktop (tray icon → Quit, not just close the window).
Check logs: %APPDATA%\Claude\logs\mcp-server-aha-mcp.log on Windows.
Verify your config JSON is valid.
Confirm AHA_API_TOKEN and AHA_DOMAIN are set in the env block.

401 / 403 errors

Check that AHA_API_TOKEN is correct and hasn't expired.
Confirm AHA_DOMAIN is the subdomain only (e.g. acme, not acme.aha.io).
Ensure the token has permission on the records you're touching.

Rate limit (429)

Aha! rate-limits per API token. The server surfaces the Retry-After value in the error. Slow down or stagger bulk operations.

"Unrecognized reference format"

resolve_reference accepts: PROD-123 (feature), PROD-123-1 (requirement), PROD-I-45 (idea), PROD-R-1 (release), PROD-E-7 (epic), PROD-N-12 (page). If yours doesn't match, use the specific get_* tool.

Links

npm: https://www.npmjs.com/package/@dvermagithub/aha-mcp
Upstream: https://github.com/aha-develop/aha-mcp
Aha! REST API docs: https://www.aha.io/api/resources
Aha! GraphQL schema: https://www.aha.io/api/graphql
Model Context Protocol: https://modelcontextprotocol.io

License

ISC — same as upstream.

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

aha-mcp+

Why this fork exists

Quick start

Claude Desktop

Cursor, Cline, RooCode, VS Code

What you can do

🔍 Ask questions

✍️ Make changes

🎯 Strategic context

Tool reference

📖 Read tools

✨ Ergonomic tools

✏️ Write tools

Common filters on every `list_*` tool

Environment variables

AI tools & editors

Development

Architecture

Contributing

Design notes

Troubleshooting

Links

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

aha-mcp+

Why this fork exists

Quick start

Claude Desktop

Cursor, Cline, RooCode, VS Code

What you can do

🔍 Ask questions

✍️ Make changes

🎯 Strategic context

Tool reference

📖 Read tools

✨ Ergonomic tools

✏️ Write tools

Common filters on every list_* tool

Environment variables

AI tools & editors

Development

Architecture

Contributing

Design notes

Troubleshooting

Links

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Common filters on every `list_*` tool