ChatterMate CLI & MCP server

chattermate-cli provides a command-line client and an MCP (Model Context Protocol) server for ChatterMate. A human can sign up, log in and configure agents, workflows and knowledge from the terminal; an AI agent can do the same through the MCP server.

This is an enterprise feature and depends on the enterprise backend's Personal Access Tokens (PATs).

Install

pip install -e .            # from this directory, for development
# or, once published:
pipx install chattermate-cli

Console scripts installed: chattermate (alias cmate) and chattermate-mcp.

Configure the API endpoint

By default the CLI talks to the hosted API at https://api.chattermate.chat. To target a local or self-hosted backend, set CHATTERMATE_API_URL=http://localhost:8000 (or pass --api-url). Resolution order: --api-url flag → CHATTERMATE_API_URL env → stored config → https://api.chattermate.chat.

Quick start (human)

# Create an organization + admin (community signup), or log in to an existing one
chattermate signup
chattermate login --email you@acme.com
# Signed up with Google or Microsoft? Create a token in Settings → CLI & API tokens, then:
chattermate login --token

chattermate whoami

# Mint a long-lived Personal Access Token for CI / AI agents (shown once!)
chattermate token create laptop-cli
chattermate token list
chattermate token revoke <token-id>

# Configure resources
chattermate agent list
chattermate agent create --name "Support" --type CUSTOMER_SUPPORT -i "Be concise"
chattermate workflow get <agent-id>
chattermate workflow create --agent-id <agent-id> --name "Onboarding"
chattermate knowledge add-url --website https://docs.acme.com --agent-id <agent-id>
chattermate knowledge status <queue-id>

# Inspect AI tickets and drive investigations
chattermate ticketing list --status open --priority urgent
chattermate ticketing show TKT-4
chattermate ticketing investigate TKT-4 --note "check the payment gateway first"
chattermate ticketing investigation TKT-4     # hypotheses, verdicts, confidence
chattermate ticketing rca TKT-4               # the root-cause document
chattermate ticketing settings show

Every command accepts --json for machine-readable output.

Authentication

Two credentials are supported:

• Personal Access Token (cmat_...) — preferred for non-interactive use. Pass it via the CHATTERMATE_TOKEN environment variable. Long-lived and revocable.
• JWT login — chattermate login stores access + refresh tokens in ~/.chattermate/config.json (mode 600) and refreshes automatically. chattermate login --token stores a PAT there instead, read from a hidden prompt — the way to log in for accounts that use Google or Microsoft sign-in.

MCP server (AI agents)

chattermate-mcp is a stdio MCP server. Point your MCP client at it with a PAT:

{
  "mcpServers": {
    "chattermate": {
      "command": "uvx",
      "args": ["--from", "chattermate-cli", "chattermate-mcp"],
      "env": {
        "CHATTERMATE_TOKEN": "cmat_...",
        "CHATTERMATE_API_URL": "https://your-chattermate-host"
      }
    }
  }
}

chattermate token create prints a ready-to-paste version of this snippet.

Tools

Read-only: whoami, list_agents, get_agent, get_workflow, get_workflow_nodes, list_knowledge, get_ingestion_status.

Mutating: create_agent, update_agent, create_workflow, update_workflow, update_workflow_nodes, add_knowledge_url, link_knowledge, unlink_knowledge.

Tests

pip install -e ".[test]"
pytest tests/