grokify/aha-mcp-server

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:

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

1. API Token: Generate an API token from your Aha! account settings
2. 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

1. "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)

2. "AHA_API_TOKEN environment variable is required"

   • Ensure you've set a valid Aha! API token
   • Check that the token has the necessary permissions

3. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Updating

Version Number

When updating the version, update it in both and .

Comparison with Other Aha! MCP Servers

License

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