Metadata-Version: 2.5
Name: zexl-mcp
Version: 0.1.0
Summary: MCP server for Zexl: ask your AI assistant about AI spend and waste, and connect a project in one go.
Project-URL: Homepage, https://tryzexl.xyz/docs/mcp
Author: Zexl
License-Expression: Apache-2.0
Keywords: ai,cost,llm,mcp,zexl
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.12
Description-Content-Type: text/markdown

# zexl-mcp

An MCP server for [Zexl](https://tryzexl.xyz). Ask your AI assistant about your AI spend ("what did we waste last week, and why?"), and let a coding agent add Zexl to a project in one go.

It only reads. It cannot send data to Zexl, change budgets, keys or members, and it never sees prompt text, because Zexl does not have any.

## Add it to your AI tool

Claude Code:

```bash
claude mcp add zexl -- uvx zexl-mcp
```

Claude Desktop, Cursor and other clients that take a JSON config:

```json
{
  "mcpServers": {
    "zexl": { "command": "uvx", "args": ["zexl-mcp"] }
  }
}
```

`uvx` comes with [uv](https://docs.astral.sh/uv/). With pip instead: `pip install zexl-mcp`, then use `zexl-mcp` as the command.

## Connect

Two ways:

1. **Let the agent do it.** Ask: "Add Zexl to this project." The agent calls `zexl_connect_start` and shows you a link and a code. Open the link, sign up or sign in (email or Google), check the code matches, pick a workspace and an environment, and approve. The agent then calls `zexl_connect_finish`, which:
   - writes `ZEXL_API_KEY` into the project's `.env` file itself, so the key never appears in the chat;
   - makes the salt (the part after the dot) on your machine; Zexl never receives it. If the project already had a Zexl key, its salt is kept so earlier calls still match;
   - adds `.env` to `.gitignore` if git would otherwise commit it;
   - saves a read key for the other tools in `~/.config/zexl/credentials.json`, readable only by you.

   The agent then follows `zexl_setup_guide` to add the SDK and checks the first call with `zexl_check_connection`.

2. **Use a read key you made.** In the Zexl dashboard, Settings > API keys, create a key with "Read figures (MCP server)". Then:

   ```bash
   claude mcp add zexl -e ZEXL_READ_KEY=zx_... -- uvx zexl-mcp
   ```

## Tools

| Tool | What it answers |
|---|---|
| `zexl_status` | Is it connected, to which workspace, and when did the last call arrive? |
| `zexl_connect_start`, `zexl_connect_finish` | Connect this project (see above) |
| `zexl_setup_guide` | Exact steps to add the SDK to a Python app, or to track Claude Code |
| `zexl_check_connection` | Did the first call arrive, and what was recorded? |
| `zexl_spend_summary` | Spend, waste by type, useful share, budget headroom, invoice coverage |
| `zexl_forecast` | Where this month will end, the likely range, and when it passes the budget |
| `zexl_top_waste` | The biggest waste findings, each with a fix |
| `zexl_breakdown` | Spend and waste per feature, model, customer or actor |
| `zexl_explain_spike` | Why one day cost more: the waste that day, and the features and models behind it |
| `zexl_pattern_runs` | The runs behind a finding, worst first |
| `zexl_run_detail` | One run step by step, with repeats, retries and cut-off answers marked |

There is also a prompt, `integrate_zexl`, that walks the agent through connecting, setup and the first check.

Every reading tool takes `days` (default 30) and `environment` (`production` by default; `staging`, `development` or `all`). A read key made for one environment always reads that environment.

## Settings

| Variable | Meaning | Default |
|---|---|---|
| `ZEXL_READ_KEY` | A read key. Overrides the saved credentials | the saved credentials |
| `ZEXL_API_URL` | The Zexl API | `https://zexl-api.fly.dev` |
| `ZEXL_CONFIG_DIR` | Where credentials are saved | `~/.config/zexl` |

To disconnect, revoke the read key in Settings > API keys and delete `~/.config/zexl/credentials.json`.

## Development

```bash
uv sync
```

```bash
uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest -q
```
