Cawly MCP server

The Cawly MCP server lets any external AI agent (Claude, Cursor, your own) operate your Cawly tenant through tools that map to the public API.

Tools

• list_contacts — list/search CRM contacts (q, per_page).
• create_contact — create a contact (name, email, phone). Phone numbers are stored in E.164.
• lookup_phone — identify a number (number, any common format). Returns the matching contact, recent inbound calls, and appointments. On the in-house Cawly account, a key with the sales.read scope also returns cold-call history, the internal CRM match, and do-not-call status.
• list_calls — list recent answered calls (q, phone, per_page).
• get_call — get a call including its audit (id).
• list_appointments — list booked appointments (per_page).

Running it

cd python
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m mcp_server

On this machine the server reads the MCP key from Dashboard → Settings. Set CAWLY_API_KEY only when you want a different key than the one in Settings.

The server authenticates with your API key, so every tool call is scoped to your organization.

Cursor setup

This repo ships a project MCP config at .cursor/mcp.json.

1. Open Dashboard → Settings. The MCP key field at the top is the full key. Generate replaces it. It is not stored in python/.env.
2. Install the server if you have not already (cd python && python -m venv .venv && .venv/bin/pip install -r requirements.txt).
3. Open Customize in the Cursor sidebar → enable the cawly server. It loads the key from Settings.
4. Confirm tools appear under Available Tools in chat. Check Output → MCP Logs if connection fails.

The agent rule in .cursor/rules/cawly-mcp.mdc tells Cursor when to prefer these tools over guessing or raw SQL.

Agents outside this repo can still set CAWLY_API_KEY and CAWLY_API_BASE in the environment. That override is optional here.

In-house Cawly account

Cold-call callbacks ("we dialed them, now they're calling back") use the same MCP key. It includes dialer history for the Cawly account. Open Settings to see the full key. Generate issues a new one and leaves it in that field.

Ask the agent to look up the callback number (lookup_phone). When sales_included is true, the result includes cold_calls (campaign, outcome, disposition, rep, notes), crm_match, and do_not_call. Use get_call on an inbound_calls id when you need the answered-call audit.