Aha! MCP Server

A comprehensive Model Context Protocol (MCP) server for Aha! that enables AI assistants to interact with your Aha! workspace data. This server provides 13 tools to retrieve and search various Aha! objects, making it easy to integrate Aha! data into AI workflows.

What is MCP?

The Model Context Protocol is an open standard that enables AI assistants to securely connect to external data sources and tools. This Aha! MCP server acts as a bridge between AI assistants (like Claude) and your Aha! workspace.

Features

13 comprehensive tools for accessing and searching Aha! objects
Secure authentication using Aha! API tokens
Easy configuration with environment variables
Multiple deployment options (stdio or HTTP)
Built with Go for performance and reliability
MIT licensed and open source

Available Tools

This server provides the following tools to retrieve and search Aha! data:

Category	Tool	Description
Search	`search_documents`	Search for documents across your Aha! workspace using GraphQL
Comments	`get_comment`	Retrieve a specific comment by ID
Epics	`get_epic`	Retrieve a specific epic by ID
Features	`get_feature`	Retrieve a specific feature by ID
Goals	`get_goal`	Retrieve a specific goal by ID
Ideas	`get_idea`	Retrieve a specific idea by ID
Initiatives	`get_initiative`	Retrieve a specific initiative by ID
Key Results	`get_key_result`	Retrieve a specific key result by ID
Personas	`get_persona`	Retrieve a specific persona by ID
Releases	`get_release`	Retrieve a specific release by ID
Requirements	`get_requirement`	Retrieve a specific requirement by ID
Teams	`get_team`	Retrieve a specific team by ID
Users	`get_user`	Retrieve a specific user by ID
Workflows	`get_workflow`	Retrieve a specific workflow by ID

All tools return JSON data including the requested object and HTTP status code.

Prerequisites

Go 1.24.1 or later
An Aha! workspace with API access
An Aha! API token (see Aha! API documentation)

Installation

Install from Source

go install github.com/grokify/aha-mcp-server/cmd/aha-mcp-server@v0.5.0

Build from Source

git clone https://github.com/grokify/aha-mcp-server.git
cd aha-mcp-server
go build ./cmd/aha-mcp-server

Configuration

Get Your Aha! Credentials

API Token: Generate an API token from your Aha! account settings
Domain: Your Aha! subdomain (e.g., if your workspace is at mycompany.aha.io, your domain is mycompany)

Environment Variables

Set the following environment variables:

export AHA_API_TOKEN="your_api_token_here"
export AHA_DOMAIN="your_aha_subdomain"

Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "aha": {
      "command": "aha-mcp-server",
      "env": {
        "AHA_API_TOKEN": "your_api_token_here",
        "AHA_DOMAIN": "your_aha_subdomain"
      }
    }
  }
}

Other MCP Clients

For other MCP clients, configure them to run the aha-mcp-server command with the required environment variables.

Usage

Basic Usage

Once configured, you can use natural language with your AI assistant to interact with Aha! data:

"Search for documents about product roadmap"
"Find all pages related to user authentication"
"Show me feature AHA-123"
"Get details for epic EPIC-456"
"What's in release REL-789?"
"Tell me about user john.doe"

Tool Parameters

Search Tool:

search_documents requires:
- query (required): Search query string
- searchable_type (optional): Document type to search (defaults to "Page")

Get Tools: Each get tool requires a specific ID parameter:

get_feature requires feature_id
get_epic requires epic_id
get_release requires release_id
And so on...

Example tool calls:

{
  "tool": "search_documents",
  "parameters": {
    "query": "product roadmap",
    "searchable_type": "Page"
  }
}

{
  "tool": "get_feature",
  "parameters": {
    "feature_id": "AHA-123"
  }
}

Advanced Configuration

HTTP Mode

You can run the server in HTTP mode for debugging or integration with other tools:

aha-mcp-server --http :8080

This will start an HTTP server on port 8080 instead of using stdio.

Command Line Options

aha-mcp-server [OPTIONS]

Options:
  -h, --http string    HTTP address (e.g., :8080) - if set, uses HTTP instead of stdio

Troubleshooting

Common Issues

"AHA_DOMAIN environment variable is required"
- Make sure you've set the AHA_DOMAIN environment variable
- Verify it contains only your subdomain (e.g., mycompany, not mycompany.aha.io)
"AHA_API_TOKEN environment variable is required"
- Ensure you've set a valid Aha! API token
- Check that the token has the necessary permissions
Connection errors
- Verify your Aha! subdomain is correct
- Check that your API token is valid and not expired
- Ensure your network allows connections to *.aha.io

Debug Mode

Run with debug logging by setting the environment variable:

export MCP_DEBUG=1

Development

Project Structure

aha-mcp-server/
├── cmd/aha-mcp-server/     # Main application entry point
├── tools/                  # Tool implementations
├── mcputil/               # MCP utility functions
├── codegen/               # Code generation templates
├── server.go              # Core server implementation
└── go.mod                 # Go module definition

Building

go build ./cmd/aha-mcp-server

Testing

go test ./...

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Updating

Version Number

When updating the version, update it in both README.md and server.go.

Comparison with Other Aha! MCP Servers

Server	Tools	License	Language
This Server	13	MIT	Go
Official Aha! MCP	3	ISC	TypeScript
popand/aha-mcp	4	ISC	TypeScript
Zapier MCP	2	SaaS	-

License

This project is licensed under the MIT License - see the LICENSE file for details.