npm package: @growhalo/mcp
Description: Halo MCP server — unified e-commerce analytics for Claude, Cursor, and other AI tools
Latest version: 0.1.2

# @growhalo/mcp

MCP (Model Context Protocol) server for [Halo](https://growhalo.ai) -- 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](https://dashboard.growhalo.ai)
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)

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

Verify with:

```bash
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`

```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](https://github.com/nicholasgasior/mcp-bridge) or [mcp-to-openai](https://github.com/nicepkg/mcp-to-openai):

```bash
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:

```json
{
  "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`:

```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)"):

```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`:

```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`:

```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:

```json
{
  "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

```bash
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