clio-mcp

A Model Context Protocol server for Clio Manage, the practice management software for law firms.

Lets Claude (or any MCP client) read and write your Clio data — contacts, matters, activities — directly from chat. Built and tested against Clio's v4 REST API.

Includes a documented workaround for Clio's silent rejection of billing_method on matter creation — see docs/flat-fee-workaround.md and the Confirmed Clio API quirks section below.

Tools (10)

Tool	Purpose
clio_who_am_i	Auth check — confirm credentials work
clio_create_company_contact	Create entity client (Inc., LLC, etc.)
clio_create_person_contact	Create individual client
clio_create_matter	Create matter, optional default attorney
clio_create_flat_fee_activity	Add a flat-fee billable line item — the workaround
clio_find_contact	Search by name and/or email
clio_find_matter	Search by display_number, query, or client_id
clio_delete_matter	Cleanup test data
clio_delete_contact	Cleanup test data
clio_api_request	Generic v4 API escape hatch

Quick start

# 1. Clone and install
git clone https://github.com/Lawyered0/clio-mcp.git
cd clio-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2. Get OAuth credentials from Clio (one-time, ~5 min)
#    See "Getting Clio OAuth credentials" below for the full dance.
#    You'll end up with: CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN.

# 3. Configure
cp .env.example .env
# edit .env with your credentials and (optional) default attorney id

# 4. Test it works (Ctrl+C to exit)
python clio_mcp_server.py --stdio

# 5. Wire it into your MCP client (verified paths below)
#    - Claude Desktop:   build a DXT (see docs/claude-desktop-dxt.md)  ← recommended
#    - Claude Code CLI:  edit ~/.claude/settings.json (see below)
#    - MCP Inspector:    mcp dev clio_mcp_server.py  (for development)

Verified clients

This server has been used in production against the following MCP clients:

Client	Transport	How to wire	Status
Claude Desktop (Code tab and regular chat)	stdio	DXT extension — see docs/claude-desktop-dxt.md	✅ Verified
Claude Code CLI	stdio	~/.claude/settings.json — see below	✅ Verified
MCP Inspector	stdio	mcp dev clio_mcp_server.py	✅ Verified
Cowork / claude.ai web / other URL-based hosts	HTTPS	Would need a public tunnel + auth on the server	⚠️ Not pursued — see HTTP mode notes

TL;DR: if you're on Mac, install via DXT into Claude Desktop. If you're already a Claude Code CLI user, the JSON config is two lines. Either path takes ~5 minutes once you have OAuth credentials.

HTTP mode (not recommended yet)

The server can also run as an HTTP service:

python clio_mcp_server.py    # binds 127.0.0.1:8765/mcp by default

This was built for use with URL-based connectors (Cowork, claude.ai web, etc.) but those hosts typically require HTTPS, often reject 127.0.0.1 URLs, and may have additional security policies. Making this safe for production use means: terminating TLS (e.g. Caddy with tls internal), exposing it via a tunnel (e.g. Cloudflare Tunnel), and adding header-based auth inside the server. None of that is implemented or verified. PRs welcome.

Claude Code CLI config

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "clio": {
      "command": "/absolute/path/to/clio-mcp/.venv/bin/python",
      "args": [
        "/absolute/path/to/clio-mcp/clio_mcp_server.py",
        "--stdio"
      ]
    }
  }
}

Restart your Claude Code session, then try clio_who_am_i to verify.

Claude Desktop config (DXT)

Claude Desktop uses DXT extensions. See docs/claude-desktop-dxt.md for a working manifest template and install instructions. Note: Claude Desktop requires a full app restart (Cmd+Q + relaunch) before a newly-installed DXT appears in any session's tool registry.

.env

CLIO_CLIENT_ID=<from Clio developer portal>
CLIO_CLIENT_SECRET=<from Clio developer portal>
CLIO_REFRESH_TOKEN=<from initial OAuth dance — see docs/oauth-setup.md>

# Optional: defaults to US (app.clio.com). For other regions:
#   CA: https://ca.app.clio.com/api/v4/  +  https://ca.app.clio.com/oauth/token
#   EU: https://eu.app.clio.com/api/v4/  +  https://eu.app.clio.com/oauth/token
#   AU: https://au.app.clio.com/api/v4/  +  https://au.app.clio.com/oauth/token
CLIO_BASE_URL=https://app.clio.com/api/v4/
CLIO_TOKEN_URL=https://app.clio.com/oauth/token

# Optional: if set, used as the default responsible_attorney + originating_attorney
# on clio_create_matter when the caller doesn't pass attorney_id explicitly.
CLIO_DEFAULT_ATTORNEY_ID=

chmod 600 .env for hygiene.

Getting Clio OAuth credentials (one-time)

This is the trickiest part of setup. Clio uses OAuth 2.0 authorization-code flow — you do this dance once to mint a refresh token, then the server handles access-token refreshes automatically. The refresh token is long-lived, so you should only ever do this once per OAuth app (unless the token gets revoked).

Step 1 — Create a developer application in Clio

Sign in to Clio and go to Settings → Developer Applications. Direct URL by region:

• US: https://app.clio.com/settings/developer_applications
• CA: https://ca.app.clio.com/settings/developer_applications
• EU/UK: https://eu.app.clio.com/settings/developer_applications
• AU: https://au.app.clio.com/settings/developer_applications

Click New Application. Fill in:

• Name: anything (e.g. Clio MCP)
• Redirect URI: http://localhost:8765/callback (Clio just needs the code to land somewhere — the page will fail to load when you're redirected there, that's expected and fine)
• Scope: check every scope you might want to use — adding scopes later requires re-running this whole dance. At minimum: contacts, matters, activities, users. Add bills, calendar, documents if you'll extend.

Save. You get back:

• Client ID (visible in the app list anytime)
• Client Secret (shown once on creation — copy it now, you cannot retrieve it later)

Step 2 — Get an authorization code

Visit this URL in your browser, substituting YOUR_CLIENT_ID and your region's host:

https://app.clio.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8765/callback

Approve. Your browser will redirect to http://localhost:8765/callback?code=XXXXXXXX... and show a "connection refused" error page. Ignore the error — copy the code=XXXXXXXX value out of the browser's address bar.

The code is single-use and expires in ~10 minutes. Move quickly to Step 3.

Step 3 — Exchange the code for a refresh token

curl -X POST https://app.clio.com/oauth/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=THE_CODE_FROM_STEP_2" \
  -d "redirect_uri=http://localhost:8765/callback"

(Substitute your region's host if not US.)

Response:

{
  "access_token": "<short-lived; ignore>",
  "token_type": "bearer",
  "expires_in": 2592000,
  "refresh_token": "<this is the one you want>"
}

Copy the refresh_token — that's what goes into .env as CLIO_REFRESH_TOKEN. The access_token you can discard; the server mints fresh ones on demand.

Step 4 — Drop into .env

CLIO_CLIENT_ID=<from Step 1>
CLIO_CLIENT_SECRET=<from Step 1>
CLIO_REFRESH_TOKEN=<from Step 3>

Run clio_who_am_i via your MCP client. If it returns 200 with your user record — you're done forever. If 401 — re-run from Step 2 (the code expired, or the redirect URI didn't match exactly).

Common gotchas

• redirect_uri must match EXACTLY between the app config, the /oauth/authorize URL, and the /oauth/token POST — including trailing slash, port, and protocol. Mismatches return generic 400 invalid_grant.
• Don't reuse the code — it's single-use. If you get invalid_grant on Step 3, the code probably expired (10 min limit) or was already used.
• Region matters — if your Clio account is on ca.app.clio.com, use that host throughout. Mixing US and non-US endpoints in the dance returns 400 invalid_grant or 401 later.
• Scope changes require re-doing the dance. If you add bills to the app's scopes later, you need a new auth code → new refresh token. Existing tokens don't auto-acquire new scopes.

For re-authorization (if your refresh token ever gets revoked) and additional troubleshooting, see docs/oauth-setup.md.

Confirmed Clio API quirks

These were discovered empirically against the live API. Trust them, don't re-derive:

Region routing

Clio runs on regional hosts. Mixing region endpoints in a single request/response cycle returns 401 invalid_token — a token minted at one region won't authenticate against another region's API. Pick one host and stick with it for both OAuth and API calls.

Region	Host
US	app.clio.com
CA	ca.app.clio.com
EU/UK	eu.app.clio.com
AU	au.app.clio.com

billing_method is silently ignored on POST /matters.json

This is the big one. Every value sent for billing_method ("flat", "Flat", "FLAT", "FlatRate", "flat_fee", "contingency", integers, etc.) results in billing_method: "hourly" on subsequent GET. PATCH after creation also returns 200 but doesn't change the value. ~16 companion field guesses (flat_rate_amount, flat_fee_amount, rate, matter_rate, billing_preference, etc.) all silently ignored too. The Clio web UI uses a private endpoint not exposed in the public REST API.

Workaround: leave matters as "hourly" and add a flat-amount Activity. See docs/flat-fee-workaround.md and use clio_create_flat_fee_activity.

TimeEntry total math

TimeEntry.total = quantity_in_hours × rate, not × price. So a TimeEntry with quantity_in_hours: 0 always totals $0 regardless of price. For flat-fee line items, use ExpenseEntry (total = quantity × price) — qty=1, price=N → total=N.

Activity field-name aliases

• POST accepts both description and note for the line-item text. GET only accepts note in ?fields=... — querying description returns 400 InvalidFields.
• rate is NOT a valid GET field on activities (returns 400). Use price × quantity.

matter_id filter footgun on /activities.json

List filter param is matter_id (singular int). matter or matter[id] are silently ignored and return account-wide activities — typo here returns wrong results without an error.

Default GET on activities returns minimal fields

A bare GET /activities/{id}.json returns only id and etag. You must explicitly pass ?fields=id,type,date,note,total,price,quantity,non_billable,... to get anything useful.

Address name is enum-validated

Must be exactly "Work", "Home", "Billing", or "Other". The natural-sounding "Business" returns 422. The _normalize_address helper auto-coerces invalid/missing names to "Work".

Mutating payloads must be wrapped

All POST/PATCH bodies must be {"data": {...}}. Sending the payload at root fails. The named tools handle this; the generic clio_api_request does NOT add the wrapper for you.

Contact type discriminator

Use "type": "Company" for entities (Inc., LLC, Ltd., numbered companies) and "type": "Person" for individual humans. Both POST to /contacts.json.

Refresh tokens may or may not rotate

Depends on the OAuth app config. The token manager handles both cases — if the refresh response includes a new refresh_token, it persists to .clio_tokens.json; if not, the .env value stays canonical. You don't need to reason about this in normal use.

Access token TTLs vary

Some accounts get ~1 hour TTL, others get 30 days (expires_in: 2592000). The token manager honors whatever the server returns.

Clio silently accepts unknown POST fields

Sending {"data": {"client": {"id": X}, "description": "...", "zzz_bogus": 1}} to /matters.json returns 201 with the unknown field dropped. Validation errors are NOT a reliable way to discover valid field names — you have to read the docs (or read this README).

/contacts.json and /matters.json deletes are idempotent-ish

DELETE returns 204 on success. DELETE on an already-deleted resource returns 404. DELETE on a contact with open bills returns 409 with a specific error code; on a contact that's a client of an open matter returns 422.

Bills are soft-deleted

DELETE on /bills/{id}.json returns 204 immediately, but the bill is moved to "void" state rather than purged from records. Probably an accounting/audit-trail design choice. Voided bills eventually drop off list endpoints.

practice_area_id doesn't drive billing

You might think setting practice_area_id to a "small claims" area would make the matter flat-fee. It doesn't. Practice areas are pure metadata; they don't affect any billing fields.

Architecture

The server is a single Python file (clio_mcp_server.py) using FastMCP from the official Anthropic MCP SDK. It runs on demand (stdio mode for Claude Code / Claude Desktop / MCP Inspector) or as a long-lived HTTP service (for URL-based connectors).

The token manager (ClioTokenManager) handles OAuth refresh transparently — every API call checks the cached access token, refreshes if expired (with a 60s safety buffer), and persists rotated refresh tokens to .clio_tokens.json (chmod 600).

All tools return a uniform {"status_code": int, "body": <parsed JSON>} shape so error payloads from Clio's validator come through verbatim — useful when something doesn't work as expected.

Contributing

PRs welcome, especially for:

• Additional tools (bills, trust requests, calendar entries, document uploads, etc.)
• Confirmed quirks I haven't documented
• Region/locale support
• Tests (the empirical findings would benefit from a recorded-cassette test suite)

If you discover Clio API behavior that contradicts what's documented here, please open an issue with a reproduction.

License

MIT. See LICENSE.

Acknowledgements

Built from frustration with the official documentation. The flat-fee workaround in particular took several hours of empirical testing to uncover — written up in docs/flat-fee-workaround.md so the next person doesn't have to.

By @BitGrateful.