aha-mcp

An MCP (Model Context Protocol) server for Aha! focused on productivity and LLM context. Give your AI assistant direct access to your Aha! tickets so you can ask things like:

"What are my current sprint tickets?" "Show me what's in progress in DAI" "Find the ticket about the jailbreak issue"

Installation

Requires Node.js 18+ or Bun 1.0+.

Claude Desktop (recommended)

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop — the Aha! tools will appear automatically.

Other MCP clients

Any client that supports the MCP stdio transport can run:

npx @goolyio_k/aha-mcp

with AHA_API_TOKEN and AHA_DOMAIN set in the environment.

Getting your credentials

| Variable | Where to find it | |---|---| | AHA_API_TOKEN | Aha! → Profile → Security → Developer API keys → Generate token | | AHA_DOMAIN | Your Aha! subdomain — e.g. if you access acme.aha.io, use acme |

Tools

Read tools

| Tool | Description | |---|---| | get_my_sprint_tickets | Start here. All features assigned to you in active sprint(s), grouped by project. | | get_my_features | All features assigned to you across all projects, with optional filters. | | get_me | Who am I — resolves the authenticated user's name, email, and ID. | | list_projects | List all Aha! workspaces/projects you have access to. | | list_iterations | List sprints for a project, filterable by status (PLANNING / ACTIVE / COMPLETE). | | list_features | Flexible feature querying — filter by project, user, sprint, status, or any combination. | | get_feature | Full detail on a single feature by reference number, e.g. DAI-1048. | | get_feature_comments | Get all comments on a feature by reference number. | | search_features | Full-text search across features. | | list_notes | List notes (knowledge base pages) for a product/project. | | get_note | Full detail and body of a single note by ID or reference number. |

Write tools ⚠️

These modify data in Aha! and are clearly marked so your AI assistant treats them carefully.

| Tool | Description | |---|---| | update_feature_status | Change a feature's workflow status. | | add_feature_comment | Post a comment on a feature. | | create_feature | Create a new feature in a project. | | create_note | Create a new note (knowledge base page) in a product. | | update_note | Update an existing note's title, body, or parent folder. |

Example prompts

Once connected, try asking Claude:

• "What are my tickets for this sprint?"
• "Show me everything in progress in the AI Team project"
• "Get the details for DAI-1048"
• "Search for tickets about jailbreak"
• "What sprints are active in the AI Team project?"
• "Add a comment to DAI-1007 saying I've started investigating" ⚠️
• "List all notes in the DAI project"
• "Show me the content of note DAI-N-5"
• "Create a note in DAI called 'Architecture Decision: Auth Flow'" ⚠️

Architecture

src/
├── index.ts         # MCP server entry point (STDIO transport)
├── client.ts        # GraphQL + REST HTTP client, user caching
├── queries.ts       # All GraphQL query/mutation strings
├── models/          # TypeScript interfaces for Aha! domain models
│   ├── common.ts    # Note, PageInfo, Tag, Estimate
│   ├── page.ts      # AhaPage (knowledge base note — REST API)
│   ├── user.ts      # User
│   ├── workflow.ts  # WorkflowStatus, InternalMeaning enum
│   ├── project.ts   # Project
│   ├── iteration.ts # Iteration, IterationStatus enum
│   └── feature.ts   # Feature
└── tools/
    ├── read.ts      # Read-only tool implementations
    └── write.ts     # Mutation tool implementations

See docs/graphql-schema.md for a full summary of the Aha! GraphQL API schema used by this server.