> # ⚠️ Deprecated — do not use for new projects
>
> `sealmetrics-mcp` is no longer maintained. It targets the **legacy Sealmetrics
> v1 API** (`app.sealmetrics.com`) and exposes 8 tools.
>
> The supported server exposes **49 tools** against the current API:
>
> **Hosted — nothing to install:**
> ```bash
> claude mcp add --transport http sealmetrics https://mcp.sealmetrics.com/mcp
> ```
>
> **Local:**
> ```bash
> npx -y @sealmetrics/mcp
> ```
>
> Setup for Claude, ChatGPT, Cursor, Codex and VS Code:
> **https://docs.sealmetrics.com/integrations/mcp-server**

# Sealmetrics MCP Server

A Model Context Protocol (MCP) server that connects AI assistants like Claude to your Sealmetrics analytics data. Query traffic, conversions, and marketing performance using natural language.

## Features

- **Traffic Analysis**: Query traffic by source, medium, campaign, or country
- **Conversions**: Get sales and conversion data with attribution
- **Microconversions**: Track add-to-cart, signups, and other engagement events
- **Funnel Analysis**: Analyze conversion funnel performance
- **ROAS Evolution**: Track return on ad spend over time
- **Page Performance**: Analyze page views and landing page effectiveness
- **Pixel Generation**: Generate tracking pixels for Google Tag Manager

## Installation

Install the package using `pipx` (recommended) or `pip`:

```bash
# Using pipx (recommended - isolated environment)
brew install pipx  # macOS
pipx install sealmetrics-mcp

# Or using pip
pip install sealmetrics-mcp
```

## Claude Desktop Configuration

Add to your Claude Desktop configuration file:

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

### Option A: Using pipx (Recommended)

If you installed with `pipx`, the executable is at `~/.local/bin/sealmetrics-mcp`:

```json
{
  "mcpServers": {
    "sealmetrics": {
      "command": "/Users/YOUR_USERNAME/.local/bin/sealmetrics-mcp",
      "args": [],
      "env": {
        "SEALMETRICS_API_TOKEN": "your-api-token-here",
        "SEALMETRICS_ACCOUNT_ID": "your-account-id-here"
      }
    }
  }
}
```

> **Note**: Replace `YOUR_USERNAME` with your actual username. You can find the path by running `which sealmetrics-mcp` after installation.

### Option B: Using uvx

If you have `uv` installed (`brew install uv`):

```json
{
  "mcpServers": {
    "sealmetrics": {
      "command": "uvx",
      "args": ["sealmetrics-mcp"],
      "env": {
        "SEALMETRICS_API_TOKEN": "your-api-token-here",
        "SEALMETRICS_ACCOUNT_ID": "your-account-id-here"
      }
    }
  }
}
```

### Option C: Using Python directly

If the package is installed in a virtual environment or globally:

```json
{
  "mcpServers": {
    "sealmetrics": {
      "command": "python",
      "args": ["-m", "sealmetrics_mcp"],
      "env": {
        "SEALMETRICS_API_TOKEN": "your-api-token-here",
        "SEALMETRICS_ACCOUNT_ID": "your-account-id-here"
      }
    }
  }
}
```

## After Configuration

1. Save the configuration file
2. **Restart Claude Desktop completely** (Cmd+Q on macOS, then reopen)
3. The Sealmetrics tools should appear in Claude's available tools

## Troubleshooting

If the MCP server disconnects:

1. **Verify the executable path exists**:
   ```bash
   ls -la ~/.local/bin/sealmetrics-mcp
   ```

2. **Test the server manually**:
   ```bash
   SEALMETRICS_API_TOKEN="your-token" ~/.local/bin/sealmetrics-mcp
   ```
   You should see: `Starting Sealmetrics MCP server`

3. **Check Claude Desktop logs**:
   ```bash
   # macOS
   cat ~/Library/Logs/Claude/mcp-server-sealmetrics.log
   ```

4. **Common issues**:
   - Path to executable is incorrect
   - API token is invalid or expired
   - Missing environment variables
   - Claude Desktop not fully restarted

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SEALMETRICS_API_TOKEN` | Yes* | Your Sealmetrics API token (recommended) |
| `SEALMETRICS_ACCOUNT_ID` | No | Default account ID for queries |
| `SEALMETRICS_EMAIL` | Yes* | Email for login (alternative to token) |
| `SEALMETRICS_PASSWORD` | Yes* | Password for login (alternative to token) |

*Either `SEALMETRICS_API_TOKEN` or both `SEALMETRICS_EMAIL` and `SEALMETRICS_PASSWORD` are required.

## Available Tools

| Tool | Description |
|------|-------------|
| `get_accounts` | List available Sealmetrics accounts |
| `get_traffic_data` | Traffic by source, medium, campaign |
| `get_conversions` | Sales and conversion data |
| `get_microconversions` | Add-to-cart, signups, etc. |
| `get_funnel_data` | Conversion funnel analysis |
| `get_roas_evolution` | ROAS over time |
| `get_pages_performance` | Page views and landing pages |
| `generate_conversion_pixel` | Generate tracking pixel code |

## Example Queries

Once configured, you can ask Claude questions like:

- "How much traffic did we get from Google Ads yesterday?"
- "Show me conversions from organic search this month"
- "What's our ROAS evolution for the last 30 days?"
- "Which landing pages are performing best?"
- "Generate a conversion pixel for newsletter signups"

## Getting Your API Token

1. Log in to your Sealmetrics dashboard
2. Go to **Settings** → **API**
3. Generate a new API token
4. Copy the token to your Claude Desktop configuration

## Support

- Documentation: https://sealmetrics.com/docs
- Issues: https://github.com/sealmetrics/mcp-server/issues
- Email: support@sealmetrics.com

## License

MIT License - see LICENSE file for details.