Klaxon

Appearance

Getting Started ​

Klaxon is a notification platform that connects AI agents to humans via the Model Context Protocol (MCP). Agents send notifications and ask questions; humans respond on their phone, browser, or desktop.

Quick Start (Docker Compose) ​

bash
git clone https://github.com/ottercoders/klaxon.git
cd klaxon
docker compose up -d

This starts:

  • Klaxon server on http://localhost:3000
  • PostgreSQL 16 on port 5432
  • Redis 7 on port 6379

The server applies database migrations automatically on startup.

Create Your First Notification ​

Once the server is running, an agent can send a notification via MCP:

bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "klaxon.notify",
      "arguments": {
        "title": "Deploy complete",
        "message": "v2.1.0 is live on production",
        "level": "success"
      }
    }
  }'

Or use the REST API directly:

bash
curl -X POST http://localhost:3000/api/items \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "title": "Deploy complete",
    "message": "v2.1.0 is live on production",
    "level": "success"
  }'

Run the Web Client ​

bash
pnpm install
pnpm --filter @klaxon/web dev

Open http://localhost:5173, configure the server URL in Settings, and log in.

Next Steps ​