@dvermagithub/aha-mcp

v0.3.0

Published

14 days ago

MCP server for Aha! via REST v1 and GraphQL. Fork of aha-mcp with expanded read coverage (releases, epics, ideas, initiatives, goals, strategic models, key results, workflows, integrations, and more), ergonomic tools (resolve_reference, search_global, get

0High
0Medium
0Low

dvermagithub

aha mcp model-context-protocol ai api rest claude

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 [email protected]"
"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.

Add to .vscode/settings.json:

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

See VS Code MCP docs.

Settings → MCP → Add new Global MCP Server:

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

Edit cline_mcp_settings.json via Cline MCP Server settings:

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

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

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.

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.

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

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.

License

ISC — same as upstream.