Aha.io MCP server

Aha MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Aha.io's product management platform. Features offline database synchronization, vector embeddings for semantic search, and comprehensive workflow automation.

🔧 Client Configuration

MCP Registry

This server is published to the official MCP Registry as io.github.cedricziel/aha-mcp, so a client that browses the registry can install it without any of the configuration below:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.cedricziel/aha-mcp"

The registry holds metadata only. Its entry points at the three artifacts described below — the npm package, the ghcr.io image and the .mcpb desktop extension — and a client picks whichever it can run. Either way the server needs AHACOMPANY and AHATOKEN.

Claude Desktop Extension (easiest)

Download aha-mcp-v.mcpb from the latest release and open it with Claude Desktop, which will prompt you for your Aha.io subdomain and API token. No Node.js or Docker setup and no manual JSON editing required.

The extension exposes 54 tools that query Aha.io directly, so results are always current and nothing is stored locally. Cross-record search is served by Aha.io's own index — see Search.

Claude Desktop Configuration

To use this MCP server with Claude Desktop, add the following to your claudedesktopconfig.json:

Using npx:

{
  "mcpServers": {
    "aha": {
      "command": "npx",
      "args": ["@cedricziel/aha-mcp"],
      "env": {
        "AHA_COMPANY": "your-company",
        "AHA_TOKEN": "your-api-token"
      }
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "aha": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "AHA_COMPANY=your-company",
        "-e", "AHA_TOKEN=your-api-token",
        "ghcr.io/cedricziel/aha-mcp"
      ]
    }
  }
}

Note: Replace your-company and your-api-token with your actual Aha.io subdomain and API token.

🚀 Getting Started

Quick Start with npx

You can run the MCP server directly using npx without installing it globally:

# Set environment variables
export AHA_COMPANY="your-company"  # Your Aha.io subdomain
export AHA_TOKEN="your-api-token"   # Your Aha.io API token

# Run the server
npx @cedricziel/aha-mcp

Quick Start with Docker

You can also run the MCP server using Docker:

# Set environment variables
export AHA_COMPANY="your-company"  # Your Aha.io subdomain
export AHA_TOKEN="your-api-token"   # Your Aha.io API token

# Run in stdio mode (default)
docker run --rm -e AHA_COMPANY="$AHA_COMPANY" -e AHA_TOKEN="$AHA_TOKEN" ghcr.io/cedricziel/aha-mcp

# Run in Streamable HTTP mode (recommended for remote access)
docker run --rm -p 3001:3001 -e AHA_COMPANY="$AHA_COMPANY" -e AHA_TOKEN="$AHA_TOKEN" ghcr.io/cedricziel/aha-mcp --mode streamable-http

Development Setup

1. Install Bun if you haven't already:

curl -fsSL https://bun.sh/install | bash

1. Install dependencies:

bun install

1. Configure environment variables:

export AHA_COMPANY="your-company"  # Your Aha.io subdomain
   export AHA_TOKEN="your-api-token"   # Your Aha.io API token

1. Start the server:

# Start the stdio server (for MCP clients - default)
   bun start

   # Or start with Streamable HTTP (recommended for remote access)
   bun start -- --mode streamable-http

   # Or start the HTTP server (legacy entry point)
   bun run start:http

Shortened. The full README is on GitHub.