Query Clio matters and time data from Claude via MCP

[project]
name = "clio-legal-mcp"
version = "0.1.0"
description = "MCP server for Clio practice-management legal workflows"
readme = "README.md"
requires-python = ">=3.11"
license = { text = "MIT" }
dependencies = [
  "mcp>=1.2.0",
  "httpx>=0.27.0",
  "pydantic>=2.6.0",
]

[project.optional-dependencies]
dev = [
  "pytest>=8.0.0",
  "pytest-httpx>=0.30.0",
  "ruff>=0.4.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/clio_legal_mcp"]

[tool.ruff]
line-length = 100
target-version = "py311"

# mcp-server-clio-legal

An MCP server for legal teams using Clio practice management. Exposes five read-only tools over the Clio API v4: `list_matters`, `get_matter`, `get_matter_time_entries`, `get_matter_activity`, and `get_contact`. No writes — the server intentionally does not register create, update, or delete operations. Attorney-client data is sensitive; queries are metadata-logged only (matter names, contact names, time-entry notes, and activity descriptions are never written to logs).

> **STATUS: scaffold — not runtime-tested.** The code is structurally complete and follows the official `mcp` Python SDK conventions, but it has not been executed against a live Clio tenant. Validate endpoint paths, field names, and filter syntax against your Clio account before use. Clio's API surface (response shapes, custom-field conventions, activity type labels) varies by account tier.

## What it exposes

- `list_matters(status?, client_id?, limit?, page_token?)` — paginated matter list filtered by status and/or client
- `get_matter(matter_id)` — full matter metadata including practice area, attorneys, and custom fields
- `get_matter_time_entries(matter_id, start_date?, end_date?, limit?)` — time entries logged against a matter
- `get_matter_activity(matter_id, type?, limit?)` — all activity records (time, expense, flat-rate) for a matter
- `get_contact(contact_id)` — contact metadata: name, type, email, phone, company

The server does **not** expose document retrieval, calendar events, billing/invoice operations, task creation, or any endpoint that modifies Clio records. The read-only posture is intentional — adding any write tool requires an explicit code change reviewed against your firm's privilege and security policies.

## Setup

### 1. Install

```bash
git clone <wherever you put this>
cd mcp-server-clio-legal
python -m venv .venv
source .venv/bin/activate     # or .venv\Scripts\activate on Windows
pip install -e .
```

### 2. OAuth — create a Clio developer application

Clio uses OAuth 2.0 Authorization Code flow. There is no static API key; you must register an application and obtain tokens.

1. Sign in to the Clio developer portal: https://app.clio.com/settings/developer_applications
2. Click **Create Application**. Set the redirect URI to `http://localhost:8080/callback` for local development.
3. Under **Permissions**, select read-only access for: Matters, Contacts, Activities. Do not select write permissions unless you are extending the server with write tools and have completed a privilege review.
4. Copy the **App Key** (this is your `CLIO_CLIENT_ID`) and **App Secret** (your `CLIO_CLIENT_SECRET`).

The OAuth token exchange produces an **access token** and a **refresh token**. Access tokens expire (typically after one hour); the production posture is to use the refresh token to obtain a new access token automatically (see TODO item 2). For local development, a static access token obtained via the Authorization Code dance is sufficient.

To obtain an initial access token manually:

1. Direct your browser to: `https://app.clio.com/oauth/authorize?response_type=code&client_id=<YOUR_CLIENT_ID>&redirect_uri=http://localhost:8080/callback`
2. Authorize the application in your Clio account.
3. Clio redirects to `http://localhost:8080/callback?code=<AUTH_CODE>`.
4. Exchange the code for tokens:

```bash
curl -X POST https://app.clio.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=<AUTH_CODE>" \
  -d "client_id=<YOUR_CLIENT_ID>" \
  -d "client_secret=<YOUR_CLIENT_SECRET>" \
  -d "redirect_uri=http://localhost:8080/callback"
```

The response JSON includes `access_token` and `refresh_token`. Copy the `access_token`.

For EU, CA, or AU regions, replace `app.clio.com` with the regional host in all OAuth URLs and API calls.

### 3. Configure environment variables

#### `CLIO_ACCESS_TOKEN`

Required. The OAuth access token obtained in step 2. Set to the `access_token` value from the token exchange response.

#### `CLIO_REGION`

Optional. Clio hosts accounts in four regions; the server must use the correct regional base URL. Accepted values: `us` (default), `eu`, `ca`, `au`. Corresponds to:

- `us` → `https://app.clio.com/api/v4`
- `eu` → `https://eu.app.clio.com/api/v4`
- `ca` → `https://ca.app.clio.com/api/v4`
- `au` → `https://au.app.clio.com/api/v4`

If you are unsure of your region, check the URL you use to sign in to Clio.

#### `CLIO_CLIENT_ID` / `CLIO_CLIENT_SECRET` / `CLIO_REFRESH_TOKEN`

Not consumed by the scaffold today. Placeholder for the OAuth refresh implementation in TODO item 2. Set them now so the variables are available when you add refresh logic.

```bash
export CLIO_ACCESS_TOKEN="eyJ..."
export CLIO_REGION="us"
export CLIO_CLIENT_ID="<your app key>"
export CLIO_CLIENT_SECRET="<your app secret>"
export CLIO_REFRESH_TOKEN="<your refresh token>"
```

### 4. Register with Claude Desktop or Claude Code

**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "clio-legal": {
      "command": "python",
      "args": ["-m", "clio_legal_mcp.server"],
      "env": {
        "CLIO_ACCESS_TOKEN": "eyJ...",
        "CLIO_REGION": "us"
      }
    }
  }
}
```

**Claude Code** — add to your project's `.claude/mcp.json` or run:

```bash
claude mcp add clio-legal python -m clio_legal_mcp.server
```

Restart Claude Desktop (or reload Claude Code). You should see 5 tools registered under `clio-legal`.

### 5. Sanity-check

Ask Claude: "List my open matters in Clio." If the response returns a list of matters with `display_number` and `status` fields, the server is working. If you receive a 401, the access token has expired — re-run the token exchange (step 2). If you receive a 429, you have exceeded the 3 req/s rate limit; add a delay between rapid successive calls.

Confirm that the response does **not** include activity note text or contact addresses unless you called `get_contact` or `get_matter_activity` explicitly. The audit log should show only `tool=list_matters ts=... results=N`.

## Security model

**Read-only.** The server registers no create, update, or delete tools. Adding any write path requires editing `server.py` — a deliberate friction point so that write access is a reviewed decision, not an accidental addition.

**Token scope.** The OAuth token's permissions are bounded by the scopes granted during the authorization dance (step 2). If you granted read-only Matters + Contacts + Activities, the token cannot modify records even if a write call were attempted. Provision the narrowest scope your use case requires.

**Who sees what.** Any user with access to the Claude Desktop or Claude Code session that has the `clio-legal` MCP registered can query any matter, contact, or activity the OAuth token's account can see. This means:

- If the token is a partner's Clio account, that partner's entire matter list is queryable.
- If you share the MCP registration across a team, every team member's Claude session can query any matter in the token holder's account.

In a multi-attorney firm, the appropriate posture is a dedicated service-account Clio user with restricted matter access, not a partner's personal account. Document the service account in your security policy.

**Attorney-client confidentiality.** Matter descriptions, time-entry notes, activity notes, and contact records are protected by attorney-client privilege and confidentiality rules. The MCP server routes all responses to Claude's context window, which means:

- The data flows through Anthropic's API (governed by Anthropic's data processing terms).
- Claude's context window is not permanently stored beyond the session, but the conversation log in Claude Desktop may persist on disk.

Review these implications with counsel before deploying to production. The scaffold is not a substitute for a firm-level AI policy that addresses privilege and confidentiality.

**Audit log.** The logger records tool name, timestamp, and result count only — never matter names, contact names, activity descriptions, or any content that could reveal case strategy or client identity.

## Known limits and TODOs (before production use)

1. Validate Clio API v4 field names and filter parameter syntax against your tenant — Clio's response shapes differ by account tier and feature flags. The `fields` strings in `server.py` follow the documented v4 conventions but have not been executed against a live account.
2. Implement OAuth token refresh using `CLIO_CLIENT_ID`, `CLIO_CLIENT_SECRET`, and `CLIO_REFRESH_TOKEN`. Static access tokens expire after approximately one hour; a production deployment needs automatic refresh via `POST https://app.clio.com/oauth/token` with `grant_type=refresh_token`.
3. Add request-level retries with exponential backoff for HTTP 429 responses. Clio enforces a 3 requests/second per-application rate limit; burst patterns (e.g., fetching all matters then all time entries immediately) will hit this.
4. Wire structured logging via `python-json-logger` piped to your matter-management audit trail. The current logger writes plain text; structured JSON simplifies downstream aggregation and privilege-compliant log scrubbing.
5. Add a matter-access guard: refuse to return matters that the authenticated user does not have explicit permission to see in Clio. The current scaffold relies entirely on Clio's API access control — if the OAuth token's account has broad matter access, so does the MCP server.
6. Write integration tests against a Clio sandbox account. The Clio developer portal provides sandbox credentials for testing without touching production data.
7. Add Sentry / OpenTelemetry export — but scrub matter names, contact names, and note text before transmission. Only identifiers (matter_id, contact_id) and counts are safe to export.

"""clio_legal_mcp — MCP server for Clio practice-management legal workflows."""

__version__ = "0.1.0"

"""
clio-legal-mcp — MCP server for legal teams using Clio practice management.

Exposes read-only tools over the Clio API v4: list_matters, get_matter,
get_matter_time_entries, get_matter_activity, and get_contact. No writes —
the server intentionally does not register create/update/delete operations.
Attorney-client data is sensitive; queries are metadata-logged only (no
matter names, contact names, or time-entry descriptions written to logs).

Clio API v4 uses OAuth 2.0 Authorization Code flow. This scaffold expects a
long-lived access token passed via the CLIO_ACCESS_TOKEN env var (see README
for the OAuth dance to obtain one). A production deployment should implement
OAuth refresh using CLIO_CLIENT_ID + CLIO_CLIENT_SECRET + CLIO_REFRESH_TOKEN.

Regional base URLs:
  US:  https://app.clio.com/api/v4
  EU:  https://eu.app.clio.com/api/v4
  CA:  https://ca.app.clio.com/api/v4
  AU:  https://au.app.clio.com/api/v4

Rate limits (per Clio docs): 3 requests/second per application token.
HTTP 429 is returned when the limit is exceeded.

STATUS: scaffold — not runtime-tested. Validate against your Clio tenant,
adjust field names to match your account's custom-property conventions, and
complete the OAuth refresh implementation (TODO item 2) before production use.

Run as: python -m clio_legal_mcp.server
"""

from __future__ import annotations

import logging
import os
from datetime import datetime, timezone
from typing import Any

import httpx
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import TextContent, Tool

# ----- Configuration (read from env at startup) -----

CLIO_ACCESS_TOKEN = os.environ.get("CLIO_ACCESS_TOKEN")
CLIO_REGION = os.environ.get("CLIO_REGION", "us").lower()

_REGION_BASES: dict[str, str] = {
    "us": "https://app.clio.com/api/v4",
    "eu": "https://eu.app.clio.com/api/v4",
    "ca": "https://ca.app.clio.com/api/v4",
    "au": "https://au.app.clio.com/api/v4",
}

API_BASE = _REGION_BASES.get(CLIO_REGION, _REGION_BASES["us"])

# Privilege-aware logger: NEVER include matter names, contact names, time-entry
# descriptions, or note text in log records. Only metadata: timestamp, tool
# name, and result count. Surfacing matter identifiers or activity descriptions
# would create a discoverable record of case activity.
audit_log = logging.getLogger("clio_legal_mcp.audit")


def require_config() -> None:
    if not CLIO_ACCESS_TOKEN:
        raise RuntimeError(
            "CLIO_ACCESS_TOKEN env var is required. See README §OAuth for how to obtain one."
        )


def auth_headers() -> dict[str, str]:
    return {
        "Authorization": f"Bearer {CLIO_ACCESS_TOKEN}",
        "Content-Type": "application/json",
    }


def log_invocation(tool: str, result_count: int | None = None) -> None:
    """Metadata-only audit record. Never includes matter names, contact names,
    time-entry descriptions, or any content that could reveal case strategy."""
    audit_log.info(
        "tool=%s ts=%s results=%s",
        tool,
        datetime.now(timezone.utc).isoformat(),
        result_count if result_count is not None else "n/a",
    )


# ----- Clio API v4 HTTP helpers -----


async def clio_get(path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
    """GET from Clio API v4. Raises httpx.HTTPStatusError on 4xx/5xx."""
    async with httpx.AsyncClient(timeout=30.0) as client:
        r = await client.get(f"{API_BASE}{path}", headers=auth_headers(), params=params)
        r.raise_for_status()
        return r.json()


# ----- Field helpers -----
# Clio's API returns only `id` and `etag` by default unless you specify `fields`.
# These helpers build the fields param for the most useful subsets.

MATTER_FIELDS = (
    "id,display_number,description,status,open_date,close_date,"
    "client{id,name,type},"
    "practice_area{id,name},"
    "responsible_attorney{id,name},"
    "originating_attorney{id,name},"
    "custom_field_values{id,field_name,value}"
)

TIME_ENTRY_FIELDS = (
    "id,type,date,quantity,price,note,non_billable,"
    "matter{id,display_number},"
    "user{id,name},"
    "activity_description{id,name}"
)

CONTACT_FIELDS = (
    "id,name,type,email_addresses{address,name},"
    "phone_numbers{number,name},"
    "company{id,name}"
)

ACTIVITY_FIELDS = (
    "id,type,date,quantity_in_hours,price,note,non_billable,"
    "matter{id,display_number},"
    "user{id,name},"
    "activity_description{id,name}"
)

# ----- Server + tool registry -----

server = Server("clio-legal")


@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="list_matters",
            description=(
                "List Clio matters, optionally filtered by status ('open', "
                "'closed', 'pending') and/or client_id. Returns id, "
                "display_number, description, status, open_date, client name, "
                "and responsible attorney per matter. Paginated; default limit 50."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": ["open", "closed", "pending"],
                        "description": "Filter by matter status. Omit to return all.",
                    },
                    "client_id": {
                        "type": "integer",
                        "description": "Filter by Clio contact (client) ID.",
                    },
                    "limit": {
                        "type": "integer",
                        "default": 50,
                        "maximum": 200,
                        "description": "Max records per page (Clio cap: 200).",
                    },
                    "page_token": {
                        "type": "string",
                        "description": "Cursor token from a prior response for pagination.",
                    },
                },
            },
        ),
        Tool(
            name="get_matter",
            description=(
                "Fetch full metadata for a single Clio matter by its integer ID. "
                "Returns status, open/close dates, practice area, responsible "
                "attorney, originating attorney, client, and custom field values."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "matter_id": {
                        "type": "integer",
                        "description": "Clio matter ID (integer, not display number).",
                    }
                },
                "required": ["matter_id"],
            },
        ),
        Tool(
            name="get_matter_time_entries",
            description=(
                "Return time entries (activities of type TimeEntry) logged "
                "against a matter. Includes date, quantity (hours), billed "
                "rate, billable flag, timekeeper name, and activity description. "
                "Time-entry descriptions may contain privileged work-product "
                "references — handle with attorney-client confidentiality in mind."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "matter_id": {
                        "type": "integer",
                        "description": "Clio matter ID.",
                    },
                    "start_date": {
                        "type": "string",
                        "description": "ISO 8601 date (YYYY-MM-DD) — include entries on or after.",
                    },
                    "end_date": {
                        "type": "string",
                        "description": "ISO 8601 date (YYYY-MM-DD) — include entries on or before.",
                    },
                    "limit": {
                        "type": "integer",
                        "default": 100,
                        "maximum": 200,
                    },
                },
                "required": ["matter_id"],
            },
        ),
        Tool(
            name="get_matter_activity",
            description=(
                "Return all activity records for a matter — time entries, "
                "expense entries, and flat-fee entries — with type, date, "
                "quantity, price, and the recording user. Use this for a "
                "full billing-activity picture rather than time-only. "
                "Activity notes may contain privileged content."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "matter_id": {
                        "type": "integer",
                        "description": "Clio matter ID.",
                    },
                    "type": {
                        "type": "string",
                        "enum": ["TimeEntry", "ExpenseEntry", "FlatRateEntry"],
                        "description": "Filter to a single activity type. Omit for all.",
                    },
                    "limit": {
                        "type": "integer",
                        "default": 100,
                        "maximum": 200,
                    },
                },
                "required": ["matter_id"],
            },
        ),
        Tool(
            name="get_contact",
            description=(
                "Fetch a Clio contact (client, opposing party, or firm) by ID. "
                "Returns name, type (Person/Company), email addresses, phone "
                "numbers, and company affiliation. Contact records may include "
                "client identity information protected by confidentiality rules."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "contact_id": {
                        "type": "integer",
                        "description": "Clio contact ID.",
                    }
                },
                "required": ["contact_id"],
            },
        ),
    ]


# ----- Tool dispatch -----


@server.call_tool()
async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
    require_config()

    # ── list_matters ──────────────────────────────────────────────────────────
    if name == "list_matters":
        params: dict[str, Any] = {
            "fields": MATTER_FIELDS,
            "limit": min(arguments.get("limit", 50), 200),
        }
        if status := arguments.get("status"):
            params["status"] = status
        if client_id := arguments.get("client_id"):
            params["client_id"] = client_id
        if page_token := arguments.get("page_token"):
            params["page_token"] = page_token

        result = await clio_get("/matters.json", params)
        matters = result.get("data", [])
        # Log count only — never matter names or client names.
        log_invocation("list_matters", len(matters))
        # Strip any residual description/note text before returning to Claude
        # so that a misconfigured fields param doesn't inadvertently surface
        # privileged work-product text.
        return [TextContent(type="text", text=str(result))]

    # ── get_matter ────────────────────────────────────────────────────────────
    if name == "get_matter":
        matter_id = arguments["matter_id"]
        result = await clio_get(
            f"/matters/{matter_id}.json",
            {"fields": MATTER_FIELDS},
        )
        log_invocation("get_matter", 1)
        return [TextContent(type="text", text=str(result))]

    # ── get_matter_time_entries ───────────────────────────────────────────────
    if name == "get_matter_time_entries":
        matter_id = arguments["matter_id"]
        params = {
            "fields": TIME_ENTRY_FIELDS,
            "matter_id": matter_id,
            "type": "TimeEntry",
            "limit": min(arguments.get("limit", 100), 200),
        }
        if start := arguments.get("start_date"):
            params["date[gte]"] = start
        if end := arguments.get("end_date"):
            params["date[lte]"] = end

        result = await clio_get("/activities.json", params)
        entries = result.get("data", [])
        log_invocation("get_matter_time_entries", len(entries))
        return [TextContent(type="text", text=str(result))]

    # ── get_matter_activity ───────────────────────────────────────────────────
    if name == "get_matter_activity":
        matter_id = arguments["matter_id"]
        params = {
            "fields": ACTIVITY_FIELDS,
            "matter_id": matter_id,
            "limit": min(arguments.get("limit", 100), 200),
        }
        if activity_type := arguments.get("type"):
            params["type"] = activity_type

        result = await clio_get("/activities.json", params)
        activities = result.get("data", [])
        log_invocation("get_matter_activity", len(activities))
        return [TextContent(type="text", text=str(result))]

    # ── get_contact ───────────────────────────────────────────────────────────
    if name == "get_contact":
        contact_id = arguments["contact_id"]
        result = await clio_get(
            f"/contacts/{contact_id}.json",
            {"fields": CONTACT_FIELDS},
        )
        log_invocation("get_contact", 1)
        return [TextContent(type="text", text=str(result))]

    raise ValueError(f"Unknown tool: {name}")


# ----- Entrypoint -----


async def main() -> None:
    require_config()
    async with stdio_server() as (read, write):
        await server.run(read, write, server.create_initialization_options())


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())