claribi-mcp

Python client for the clariBI MCP Server.

The clariBI MCP Server lets you sign up users, list dashboards, run analyses, and generate reports via the Model Context Protocol. This SDK is a thin synchronous JSON-RPC client built on httpx with one typed Python method per registered server tool:

from claribi_mcp import Client

with Client(api_key="claribi_mcp_...") as client:
    client.initialize()
    dashboards = client.list_dashboards()
    print(dashboards.structured["items"])

    result = client.run_analysis(question="What was revenue last quarter?")
    print(result.text)

Install

pip install claribi-mcp

Authentication

Either:

• API key — mint a claribi_mcp_* key from Developer Portal → MCP Server → Clients & Keys and pass it as api_key=.
• OAuth 2.1 bearer token — pass auth=BearerTokenAuth(access_token=..., refresh_callable=...).

from claribi_mcp import Client, BearerTokenAuth

def refresh():
    new_token, new_expires_at = some_oauth_refresh()
    return new_token, new_expires_at

client = Client(
    auth=BearerTokenAuth(
        access_token=initial_token,
        expires_at=initial_expires_at,
        refresh_callable=refresh,
    ),
)

Tool surface

The SDK exposes one typed method per server tool. Methods are auto-generated from the live /api/mcp-server/tool-catalog/ endpoint so they always match what the server actually supports.

Headline methods (read-only):

• client.list_dashboards(limit=20, offset=0, search=None)
• client.get_dashboard(dashboard_id=...)
• client.list_reports(...), client.get_report(...)
• client.list_data_sources(...), client.get_data_source_schema(...)
• client.get_usage(), client.get_billing_status()
• client.check_pricing(tier=None)

Write methods (require analysis:run, reports:write, etc. scopes):

• client.run_analysis(question=..., wait_seconds=30)
• client.get_analysis_status(job_id=...)
• client.generate_report(name=..., template_id=None, output_format='pdf')
• client.create_checkout_session(tier='professional', billing_period='monthly')

Signup methods (no auth required):

• client.register_account(email=..., organization_name=..., accept_terms=True)
• client.verify_email(pending_id=..., code=..., password=...)

Sign up via SDK

client = Client()  # no auth — public tools only
pending = client.register_account(
    email="me@example.com",
    organization_name="My Team",
    accept_terms=True,
)
pending_id = pending.structured["pending_id"]
code = input("Enter the 6-digit code from your email: ")
verified = client.verify_email(
    pending_id=pending_id,
    code=code,
    password="a-strong-password",
)
api_key = verified.structured["mcp_api_key"]
print(f"Save this key: {api_key}")

Codegen

Regenerate the typed tool surface against your server:

python scripts/codegen.py \
    --catalog https://claribi.com/api/mcp-server/tool-catalog/ \
    --output  claribi_mcp/generated

License

MIT.