# Owlvin MCP Server

MCP server for the [Owlvin](https://owlvin.io) platform — one install, every AI tool.

Works with Claude Code, Gemini CLI, Codex, and any MCP-compatible agent.

## Install

```bash
pip install owlvin-mcp
```

## Set your API key

```bash
export OWLVIN_API_KEY=ow_live_your_key_here
```

Or create a config file:

```bash
mkdir -p ~/.config/owlvin
echo '{"api_key": "ow_live_your_key_here"}' > ~/.config/owlvin/config.json
```

Get a key:

```bash
curl -X POST https://whoisgloom--owlvin-platform-web.modal.run/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
```

## Add to your agent

### Claude Code

```bash
claude mcp add owlvin -- python -m owlvin_mcp
```

Or add to `.claude/mcp.json`:

```json
{
  "mcpServers": {
    "owlvin": {
      "command": "python",
      "args": ["-m", "owlvin_mcp"],
      "env": {
        "OWLVIN_API_KEY": "ow_live_your_key_here"
      }
    }
  }
}
```

### Gemini CLI

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "owlvin": {
      "command": "python",
      "args": ["-m", "owlvin_mcp"],
      "env": {
        "OWLVIN_API_KEY": "ow_live_your_key_here"
      }
    }
  }
}
```

### OpenAI Codex

```bash
codex --mcp-config mcp.json
```

With `mcp.json`:

```json
{
  "mcpServers": {
    "owlvin": {
      "command": "python",
      "args": ["-m", "owlvin_mcp"]
    }
  }
}
```

## Tools

### `owlvin_services`

List all available services and pricing on the platform.

No parameters.

### `owlvin_credits`

Check your credit balance and usage.

No parameters.

### `owlvin_buy_credits`

Get a Stripe Checkout URL to buy credits.

| Parameter | Type | Description |
|-----------|------|-------------|
| `amount_cents` | int | 500 ($5), 2500 ($25 + $5 bonus), or 10000 ($100 + $30 bonus) |

### `owlvin_call`

Call any service through the platform. Billing and auth handled automatically.

| Parameter | Type | Description |
|-----------|------|-------------|
| `service` | string | Service slug (e.g. "drumsplit") |
| `operation` | string | Operation name (e.g. "full", "drumbus") |
| `input_data` | string | JSON string with operation parameters. Default: "{}" |

### `owlvin_pricing`

Show credit packages and per-call costs.

No parameters.

## Config

Environment variables (take priority):

| Variable | Description |
|----------|-------------|
| `OWLVIN_API_KEY` | Your platform API key |
| `OWLVIN_API_URL` | Override API URL (default: Modal deployment) |

Config file (`~/.config/owlvin/config.json`):

```json
{
  "api_key": "ow_live_your_key_here",
  "api_url": "https://whoisgloom--owlvin-platform-web.modal.run"
}
```

## License

MIT