# Install via uvx (recommended)
uvx kickbacks-mcp

# Or install locally
pip install kickbacks-mcp
# or
pip install -e .

export KICKBACKS_API_KEY=your_api_key_here
export KICKBACKS_USER_ID=your_user_id_here  # optional

# ~/.hermes/config.yaml
mcp_servers:
  kickbacks:
    command: "uvx"
    args: ["kickbacks-mcp"]
    env:
      KICKBACKS_API_KEY: "your_key"

# Check balance
> kickbacks_balance

# See earnings breakdown
> kickbacks_earnings

# Check status & caps
> kickbacks_status

# View ad history
> kickbacks_ads_history

# Enable/disable ads
> kickbacks_set_enabled enabled=true

> kickbacks_earnings
Earnings Breakdown:
  Today: $0.42
  This Week: $7.11
  This Month: $42.50
  Total: $156.78
  Currency: USD

> kickbacks_status
Connected: ✅ | Authenticated: ✅ | Enabled: ✅ | Last sync: 2026-06-13T21:32:31 | Session: 23 impressions, 2 clicks

> kickbacks_ads_history
Ad History (showing 2 of 2):
  👁 [2026-06-13T21:32:31] Ramp - save time and money (spinner) - $0.0010
  👆 [2026-06-13T21:32:31] Bitcoin Devs Takeover Toronto (statusbar) - $0.0500

mcp_servers:
  kickbacks:
    command: "uvx"
    args: ["kickbacks-mcp"]
    env:
      KICKBACKS_API_KEY: "ghp_xxx..."
      KICKBACKS_USER_ID: "user_123"
    timeout: 60

{
  "mcpServers": {
    "kickbacks": {
      "command": "uvx",
      "args": ["kickbacks-mcp"],
      "env": {
        "KICKBACKS_API_KEY": "your_key"
      }
    }
  }
}

# Clone
git clone https://github.com/msgok/kickbacks-mcp
cd kickbacks-mcp

# Install in dev mode
pip install -e ".[dev]"

# Run directly
python -m kickbacks_mcp.server

# Run tests
pytest

kickbacks_mcp/
├── __init__.py      # Package init
├── client.py        # Kickbacks API client
├── server.py        # MCP server with tools
├── pyproject.toml   # Project config
└── README.md        # This file

# Build
pip install build
python -m build

# Publish
pip install twine
twine upload dist/*