# Katzilla

> 300+ free public & government data sources behind one API key — the data API for AI agents.

[![npm (mcp)](https://img.shields.io/npm/v/@katzilla/mcp.svg?label=%40katzilla%2Fmcp)](https://www.npmjs.com/package/@katzilla/mcp)
[![npm (sdk)](https://img.shields.io/npm/v/@katzilla/sdk.svg?label=%40katzilla%2Fsdk)](https://www.npmjs.com/package/@katzilla/sdk)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Katzilla aggregates primary-source public data — US federal, case law, health, hazards, economics, 17+ international open-data portals, Eurostat, ECB, WHO, OECD, IMF, World Bank, and more — behind a single REST API and MCP server. Every response ships with structured `citation` metadata (source, license, URL, update frequency) and `quality` scoring (freshness, uptime, completeness, confidence).

Get a free API key at <https://katzilla.dev/dashboard>.

## MCP Server

The fastest way to use Katzilla is as an MCP server in Claude Desktop, Cursor, Windsurf, Continue, or any stdio MCP client.

### Claude Desktop

Edit `claude_desktop_config.json`:

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

```json
{
  "mcpServers": {
    "katzilla": {
      "command": "npx",
      "args": ["-y", "@katzilla/mcp"],
      "env": {
        "KATZILLA_API_KEY": "kz_your_key_here"
      }
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json` (or project-local `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "katzilla": {
      "command": "npx",
      "args": ["-y", "@katzilla/mcp"],
      "env": {
        "KATZILLA_API_KEY": "kz_your_key_here"
      }
    }
  }
}
```

Restart the client — Katzilla's tools show up in the MCP menu. Full MCP package docs: [packages/mcp/README.md](packages/mcp/README.md).

## TypeScript SDK

```bash
npm install @katzilla/sdk
```

```ts
import { Katzilla } from "@katzilla/sdk";

const kz = new Katzilla({ apiKey: process.env.KATZILLA_API_KEY! });

const quakes = await kz.agent("hazards").action("usgs-earthquakes", {
  minMagnitude: 5,
});
console.log(quakes.data, quakes.citation);
```

## REST API

```bash
curl -X POST https://api.katzilla.dev/agents/hazards/actions/usgs-earthquakes \
  -H "X-API-Key: kz_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"minMagnitude": 5, "limit": 10}'
```

Public endpoints (no auth): `/health`, `/status`, `/openapi.json`, `/agents`, `/agents/tools`, `/agents/datasets`.

## Data coverage

- **US federal** — congress.gov, SEC EDGAR, Federal Register, Regulations.gov, USAspending, FEC, govinfo, State Department
- **US case law** — CourtListener (opinions at every level)
- **US health** — FDA recalls / adverse events / devices, NIH ClinicalTrials.gov, CMS, CDC
- **US hazards** — USGS earthquakes & water, NWS alerts, FEMA disasters, NASA FIRMS wildfires
- **Economics** — BLS, FRED, BEA, Census ACS, Treasury Fiscal Data
- **International portals** — UK, France, Germany, Canada, Australia, Brazil, Ireland, Spain, Italy, Poland, and more
- **International bodies** — Eurostat, ECB, WHO, OECD, IMF, World Bank, UN Comtrade, SIPRI
- …plus crypto, space, demographics, energy, transport, agriculture.

Full source list at <https://katzilla.dev>.

## Repository layout

Monorepo (pnpm workspaces).

| Package | Purpose |
| --- | --- |
| [packages/api](packages/api) | Fastify 5 REST API server |
| [packages/app](packages/app) | React 19 + Vite SPA frontend |
| [packages/sdk](packages/sdk) | Official TypeScript SDK ([npm](https://www.npmjs.com/package/@katzilla/sdk)) |
| [packages/python-sdk](packages/python-sdk) | Official Python SDK |
| [packages/mcp](packages/mcp) | Standalone MCP server ([npm](https://www.npmjs.com/package/@katzilla/mcp)) |
| [packages/core](packages/core) | Shared types, schemas, utilities |
| [packages/agents/*](packages/agents) | One package per data-source category |

## Development

```bash
pnpm install
pnpm build          # build all packages
pnpm dev            # dev mode (api + app in parallel)
pnpm dev:api        # api only
pnpm dev:app        # frontend only
pnpm typecheck      # typecheck all packages
pnpm test:e2e       # Playwright E2E tests (needs app on :5173)
```

Required env vars: `DATABASE_URL`, `JWT_SECRET`, `CREDENTIAL_ENCRYPT_KEY`.
Data-source keys (optional, BYOK): `DATA_GOV_API_KEY`, `FRED_API_KEY`, `BLS_API_KEY`, etc. See [.env.example](.env.example).

## Links

- Site & dashboard — <https://katzilla.dev>
- API docs — <https://api.katzilla.dev/openapi.json>
- Issues — <https://github.com/codeislaw101/katzilla/issues>

## License

MIT