Skip to main content

zexl-mcp

An MCP server for Zexl. 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:

claude mcp add zexl -- uvx zexl-mcp

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

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

uvx comes with 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:

    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

uv sync
uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest -q

Metadata

Release files for zexl-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zexl-mcp 0.1.0
File Size Uploaded Provenance Actions
zexl_mcp-0.1.0.tar.gz 16.3 kB Without provenance Details for zexl_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zexl-mcp 0.1.0
File Interpreter ABI Platform Actions
zexl_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for zexl_mcp-0.1.0-py3-none-any.whl

Total release size: 35.9 kB

Release files / zexl_mcp-0.1.0.tar.gz

Download URL zexl_mcp-0.1.0.tar.gz
Size 16.3 kB
Tags Source
SHA-256 checksum
How to use checksums
58241a2aea5d44e2c42a19301df54815bf59d293b553e686c08f31799d31236d
BLAKE2b-256 checksum
How to use checksums
181b66d4a41864343e183914f3a27fc43b2a60e2d6e85a9955bc530eb9180fa8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Release files / zexl_mcp-0.1.0-py3-none-any.whl

Download URL zexl_mcp-0.1.0-py3-none-any.whl
Size 19.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6f7db319048d26b64d78a541bbdcc030444464829c2aec7fe2b6b6182e3ef66d
BLAKE2b-256 checksum
How to use checksums
aedfe709ca8f6f9816b121278de02e152231e2958d658f6e0afca87c74888946
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Security for zexl-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page