Metadata-Version: 2.4
Name: metaverse-mcp
Version: 0.1.1
Summary: AI-powered Metabase interface via MCP
Requires-Python: >=3.12
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic-settings>=2.0.0
Description-Content-Type: text/markdown

# Metaverse

AI-powered interface for Metabase — query your data, build dashboards, and set up alerts using natural language.

## Skills

Use these Claude Code slash commands from any project connected to Metaverse:

| Skill | Description | Example |
|-------|-------------|---------|
| `/metaask` | Ask a data question, get a table back | `"How many customers do we have in the US?"` |
| `/metaquery` | Build and save a custom query | `"Show me the latest orders by customer #100"` |
| `/metaboard` | Build a dashboard from a description | `"Monthly overview of Gift Card sales"` |
| `/metametric` | Create or explore a reusable named metric | `"Create a Total Revenue metric on orders"` |
| `/metalert` | Set up a metric alert | `"Notify me when any provider has more than 10 refunds in an hour"` |

## What it solves

- Extracting data from databases without writing SQL manually
- Building dashboards and alerts without navigating the Metabase UI
- Exploring data structures and relationships through conversation
- Spotting patterns and anomalies by just asking

## Integrations

Works wherever Claude agents run:

- **Claude Code** — local CLI (primary target)
- **Claude Desktop** — local app via ngrok tunnel
- **Claude in Slack** — team-wide data questions *(planned)*
- **Claude in GitHub** — data questions in issues and PRs *(planned)*

## How it works

An MCP server exposes Metabase as a set of tools Claude can call — browsing databases and tables, running SQL queries, creating saved questions, assembling dashboards, and managing alerts. Claude handles the natural language layer; Metabase handles the data layer.

## Stack

- **Python** + **FastMCP** — MCP server (HTTP transport)
- **Metabase OSS** + **Postgres** — data layer, both run locally via Docker
- **Justfile** — task runner for starting services, seeding data, and config

## Agent integration

### Claude Code

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "metaverse": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

Run `just up` to start the stack, then open Claude Code. The slash commands (`/metaask`, `/metaquery`, `/metaboard`, `/metalert`) and all MCP tools are available immediately.

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "metaverse": {
      "command": "uvx",
      "args": ["--from", "metaverse-mcp", "metaverse"],
      "env": {
        "METABASE_URL": "https://your-metabase.example.com",
        "METABASE_API_KEY": "mb_xxxx"
      }
    }
  }
}
```

Restart Claude Desktop. The `metaask`, `metaquery`, `metaboard`, and `metalert` prompts appear in the UI — no slash commands needed.

> **Local Metabase only?** Claude Desktop requires HTTPS even for localhost. Run `ngrok http 3000` and use the tunnel URL as `METABASE_URL`.

### Any MCP-compatible agent

Point the agent at the running HTTP server:

```
http://localhost:8000/mcp
```

The server exposes 14 tools and 3 schema resources (`metaverse://schema`, `metaverse://database/{id}`, `metaverse://table/{id}`) that any MCP client can discover and use.

---

## Getting started

See [HOWTO.md](HOWTO.md) for full setup instructions.

```bash
just up       # start Postgres + Metabase + MCP server
just setup    # first-run: create admin account + API key
claude        # open Claude Code — skills and MCP tools are ready
```
