@growhalo/mcp

MCP (Model Context Protocol) server for Halo -- unified e-commerce analytics. Connect your AI tools to your Shopify, Meta, Google Ads, TikTok, Pinterest, Amazon, Klaviyo, and GA4 data.

20 tools | 3 resources | 4 prompts

Quick Start

1. Get your API key

1. Log into the Halo dashboard
2. Go to Settings > API Keys
3. Click Create Key and select scopes:
   • read -- analytics, orders, campaigns, store info
   • ingestion:read -- pipeline status and run details
   • ingestion:write -- trigger pulls and backfills
4. Copy the key (shown once)

2. Pick your AI tool and follow the setup below

Setup Guides

Claude Code (CLI)

claude mcp add halo -- npx -y @growhalo/mcp \
  -e HALO_API_KEY=halo_sk_your_key_here

Verify with:

claude mcp list

Claude Desktop

Edit your config file:

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

{
  "mcpServers": {
    "halo": {
      "command": "npx",
      "args": ["-y", "@growhalo/mcp"],
      "env": {
        "HALO_API_KEY": "halo_sk_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

ChatGPT (via MCP Bridge)

ChatGPT does not natively support MCP yet. Use an MCP-to-OpenAI bridge like mcp-bridge or mcp-to-openai:

npx mcp-to-openai --mcp-server "npx -y @growhalo/mcp" --env HALO_API_KEY=halo_sk_your_key_here

This exposes the Halo MCP tools as OpenAI-compatible function calls that ChatGPT can use via the API or custom GPTs.

Cursor

Open Settings > MCP Servers or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "halo": {
      "command": "npx",
      "args": ["-y", "@growhalo/mcp"],
      "env": {
        "HALO_API_KEY": "halo_sk_your_key_here"
      }
    }
  }
}

Restart Cursor after saving.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "halo": {
      "command": "npx",
      "args": ["-y", "@growhalo/mcp"],
      "env": {
        "HALO_API_KEY": "halo_sk_your_key_here"
      }
    }
  }
}

Restart Windsurf after saving.

VS Code (GitHub Copilot)

Add to your VS Code settings.json (Cmd+Shift+P > "Preferences: Open User Settings (JSON)"):

{
  "mcp": {
    "servers": {
      "halo": {
        "command": "npx",
        "args": ["-y", "@growhalo/mcp"],
        "env": {
          "HALO_API_KEY": "halo_sk_your_key_here"
        }
      }
    }
  }
}

Requires the GitHub Copilot extension with MCP support enabled.

JetBrains (IntelliJ, WebStorm, etc.)

Go to Settings > Tools > AI Assistant > MCP Servers, click +, and add:

• Name: halo
• Command: npx
• Arguments: -y @growhalo/mcp
• Environment Variables: HALO_API_KEY=halo_sk_your_key_here

Zed

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "halo": {
      "command": {
        "path": "npx",
        "args": ["-y", "@growhalo/mcp"],
        "env": {
          "HALO_API_KEY": "halo_sk_your_key_here"
        }
      }
    }
  }
}

Amazon Q Developer

Edit ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "halo": {
      "command": "npx",
      "args": ["-y", "@growhalo/mcp"],
      "env": {
        "HALO_API_KEY": "halo_sk_your_key_here"
      }
    }
  }
}

Docker

For any MCP client that supports Docker:

{
  "mcpServers": {
    "halo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "HALO_API_KEY=halo_sk_your_key_here",
        "ghcr.io/roasberry/halo-mcp:latest"
      ]
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | HALO_API_KEY | Yes | -- | Your Halo API key | | HALO_GATEWAY_URL | No | https://api.growhalo.ai | API gateway URL | | HALO_TRANSPORT | No | stdio | Transport mode (stdio) | | HALO_REQUEST_TIMEOUT_MS | No | 30000 | Request timeout in ms |

Available Tools

Stores

| Tool | Description | |---|---| | list_stores | List all stores you have access to | | get_store_detail | Store info with members and connections |

Analytics

| Tool | Description | |---|---| | get_dashboard_overview | Revenue, ROAS, CPA, spend, orders, and trends | | get_channel_metrics | Detailed metrics for a specific channel | | get_channel_mix | Spend and revenue distribution across channels | | get_efficiency_metrics | Blended ROAS, MER, CPA trends | | get_correlation_matrix | Cross-channel spend correlation analysis | | get_attribution | Attribution by channel with 1d/7d/14d/28d windows |

Data

| Tool | Description | |---|---| | list_orders | Orders with filters and pagination | | list_campaigns | Campaign performance data | | list_ad_sets | Ad set performance data | | list_ads | Ad-level performance data |

Ingestion

| Tool | Description | |---|---| | get_ingestion_status | Pipeline status for all platforms | | trigger_pull | Trigger an immediate data pull | | trigger_backfill | Trigger historical data backfill | | verify_data_coverage | Check data completeness | | get_queue_status | Job queue status | | get_run_details | Details of a specific ingestion run |

Connections

| Tool | Description | |---|---| | list_connections | All platform connections for a store | | check_connection_health | Verify a connection is healthy |

Resources

| Resource | URI | Description | |---|---|---| | Store Context | store://current | Active store info and connected platforms | | Ingestion Status | ingestion://status | Pipeline health across all platforms | | Analytics Views | analytics://views | Catalog of available views and streams |

Prompts

| Prompt | Description | |---|---| | weekly_performance_summary | Weekly report across all channels | | diagnose_roas_drop | Investigate ROAS decline | | compare_channels | Side-by-side channel comparison | | ingestion_health_check | Full pipeline health check |

Supported Platforms

Shopify, Meta (Facebook/Instagram Ads), Google Ads, TikTok (Business + Shop), Pinterest, Amazon (Seller + Ads), Klaviyo, GA4, ikas, iyzico.

Example Conversations

Once configured, ask your AI assistant:

• "What was my ROAS last week?"
• "Compare Meta vs Google Ads for March"
• "Show me all refunded orders from Shopify"
• "Which campaign had the best CPA this month?"
• "Are all my data pipelines healthy?"
• "Backfill Amazon data for January"
• "Give me a weekly performance summary"
• "How is my halo effect across channels?"

Building from Source

git clone https://github.com/Roasberry/halo-api.git
cd halo-api && pnpm install
pnpm --filter @growhalo/mcp build
HALO_API_KEY=halo_sk_... node services/mcp/dist/index.js

Troubleshooting

"HALO_API_KEY environment variable is required" -- Set the HALO_API_KEY env var.

401 errors -- API key is invalid or revoked. Generate a new one from Dashboard > Settings > API Keys.

403 errors -- API key is missing the required scope. Update scopes in the dashboard.

Timeout errors -- Increase HALO_REQUEST_TIMEOUT_MS (default 30s). Large date ranges may take longer.

npx hangs or fails -- Ensure Node.js 20+ is installed. Try npx -y @growhalo/mcp with the -y flag to skip prompts.

License

MIT