Skip to main content
Glama
smokeball-mcp

smokeball-mcp

Smokeball MCP server

CI Python 3.10+ License: MIT MCP 2026-07-28 PyPI version

Connect Claude and other MCP clients to Smokeball to manage matters, contacts, tasks, billing and documents.

Smokeball MCP server is a Model Context Protocol server for Smokeball, the law practice management platform. It registers 189 tools that read and write Smokeball data. It runs over stdio by default, for desktop clients such as Claude Desktop, and offers an opt-in stateless Streamable HTTP mode that implements MCP specification 2026-07-28. Smokeball credentials stay on the machine that runs the server: they come from the setup command and your operating system's keyring, or from environment variables, never from the client.

Features

  • Matters: create, update, archive, tag and delete matters, and manage billing configuration, roles, relationships and stages.

  • Contacts and leads: create, read, update and delete contacts and leads, with contact relations and tags.

  • Tasks and events: manage tasks, subtasks, task documents, calendar events and reminders.

  • Files and folders: upload, download and preview files, browse the folder hierarchy and read version history.

  • Billing: record fees and expenses, read invoices, manage activity codes, and work with bank accounts and trust transactions.

  • Client portal: create and update portal tasks and send portal messages.

  • Document generation: browse layout designs, add layouts to matters, merge them and read matter items.

  • Administration: manage staff, users, authorization groups and policies, plugins, webhooks and notifications.

Related MCP server: Clio Manage MCP

Tools

The server registers 189 tools. They cover firm settings, staff and users, contacts, matters, leads, matter types and stages, roles and relationships, tasks and events, memos, fees, expenses, invoices, activity codes, bank accounts and transactions, files and folders, archiving, referral types, authorization, notifications, plugins, the client portal, document layouts, matter items, integrated search and webhooks. Tools that take a webhook or plugin URL accept only hosts approved in SMOKEBALL_ALLOWED_DESTINATION_HOSTS (see Approved destination URLs).

  • add_contact_tags

  • add_contact_to_layout

  • add_file_to_matter

  • add_files_to_matter_batch

  • add_layout_to_matter

  • add_matter_tags

  • add_relationship_to_role

  • add_role_to_matter

  • archive_matter

  • create_activity_code

  • create_authorization_group

  • create_authorization_policy

  • create_contact

  • create_contact_relation

  • create_event

  • create_event_reminder

  • create_expense

  • create_fee

  • create_file_preview_request

  • create_folder

  • create_lead

  • create_matter

  • create_memo

  • create_notification

  • create_plugin

  • create_portal_task

  • create_requisition

  • create_staff_member

  • create_subtask

  • create_task

  • create_task_document

  • create_transaction

  • create_user

  • create_webhook_subscription

  • delete_activity_code

  • delete_authorization_group

  • delete_contact

  • delete_contact_relation

  • delete_event

  • delete_event_reminder

  • delete_expense

  • delete_fee

  • delete_file

  • delete_firm_user_mapping

  • delete_folder

  • delete_lead

  • delete_matter

  • delete_memo

  • delete_plugin

  • delete_staff_member

  • delete_subtask

  • delete_task

  • delete_task_document

  • delete_webhook_subscription

  • get_activity_code

  • get_authorization_group

  • get_authorization_policy

  • get_bank_account

  • get_bank_account_matter_balances

  • get_contact

  • get_contact_relation

  • get_contact_relations

  • get_contact_tags

  • get_event

  • get_event_reminders

  • get_expense

  • get_fee

  • get_file

  • get_file_download_url

  • get_file_history

  • get_file_preview_info

  • get_file_preview_info_by_version

  • get_file_upload_url

  • get_firm

  • get_firm_user_mapping

  • get_firm_user_mappings

  • get_folder_contents

  • get_folder_history

  • get_folder_path_hierarchy

  • get_invoice

  • get_invoice_download_url

  • get_layout_contacts

  • get_layout_design

  • get_layout_on_matter

  • get_lead

  • get_matter

  • get_matter_archive

  • get_matter_billing_configuration

  • get_matter_item

  • get_matter_stage

  • get_matter_tags

  • get_matter_type

  • get_memo

  • get_notification

  • get_plugin

  • get_plugin_subscription

  • get_plugin_url

  • get_protected_bank_account_balance

  • get_referral_type

  • get_relationship_on_role

  • get_relationships_on_matter

  • get_role_on_matter

  • get_roles_on_matter

  • get_root_folder_contents

  • get_search_mapping

  • get_staff_member

  • get_stage_in_set

  • get_stage_set

  • get_subtask

  • get_subtasks

  • get_task

  • get_task_document

  • get_task_documents

  • get_transaction

  • get_user

  • get_webhook_subscription

  • list_activity_codes

  • list_authorization_groups

  • list_bank_accounts

  • list_contacts

  • list_events

  • list_expenses

  • list_fees

  • list_files_on_matter

  • list_invoices

  • list_layout_designs

  • list_layouts_on_matter

  • list_leads

  • list_matter_items

  • list_matter_stage_mappings

  • list_matter_type_categories

  • list_matter_types

  • list_matters

  • list_memos_on_matter

  • list_plugin_subscriptions

  • list_plugins

  • list_referral_types

  • list_stage_sets

  • list_tasks

  • list_transactions

  • list_webhook_event_types

  • list_webhook_subscriptions

  • merge_layout

  • patch_expense

  • patch_fee

  • patch_file

  • patch_folder

  • patch_lead

  • patch_matter

  • patch_matter_archive

  • protect_funds

  • remove_contact_tags

  • remove_layout_from_matter

  • remove_matter_tags

  • remove_relationship_from_role

  • remove_role_from_matter

  • remove_user

  • resend_user_invitation

  • search_staff

  • send_portal_message

  • subscribe_to_plugin

  • test_webhook_subscription

  • unarchive_matter

  • unprotect_funds

  • unsubscribe_from_plugin

  • update_activity_code

  • update_authorization_group

  • update_authorization_policy

  • update_contact

  • update_contact_relation

  • update_event

  • update_event_reminder

  • update_expense

  • update_fee

  • update_firm

  • update_firm_user_mapping

  • update_folder

  • update_lead

  • update_matter

  • update_matter_billing_configuration

  • update_memo

  • update_plugin

  • update_portal_task

  • update_relationship

  • update_role_on_matter

  • update_staff_member

  • update_subtask

  • update_task

  • update_webhook_subscription

Prompts and resources

The server also registers three prompts and three read-only resources.

Prompt

What it does

daily_briefing

Morning briefing of open matters needing attention, overdue tasks and unbilled fees.

intake_triage

Triage a new or recently opened matter by checking its contacts, billing setup and key documents. Takes a matter_id.

billing_summary

Summary of a matter's fees, expenses, invoices and outstanding balances. Takes a matter_id.

Resource

What it holds

smokeball://matter_types

The matter types configured in your Smokeball firm.

smokeball://activity_codes

The billable activity codes configured in your Smokeball firm.

smokeball://security-notes

Security notes for this server, as Markdown.

Requirements

  • Python 3.10 or later

  • A Smokeball account with partner API access: a Client ID, a Client Secret and an API Key

  • An MCP client such as Claude Desktop

Smokeball partner access: API credentials are issued through the Smokeball partner/developer program. Contact your Smokeball account representative to request API access.

Installation

Install uv, then clone the repository and install its locked dependencies:

git clone https://github.com/RosenAdvertising/smokeball-mcp.git
cd smokeball-mcp
uv sync --locked

Releases are also published to PyPI: pip install smokeball-mcp installs version 0.2.0, which predates the HTTP mode described below. Install from source to use HTTP mode.

Configuration

Run the guided OAuth setup from your clone of the repository:

uv run --locked smokeball-mcp-setup

Setup does four things:

  1. Asks for your region (US, AU or UK).

  2. Asks for your Client ID, Client Secret and API Key.

  3. Opens your browser for Smokeball authorization and listens for the redirect at http://127.0.0.1:8768/callback.

  4. Saves the credentials to your operating system's keyring (or the file fallback described under Credential storage) and the OAuth tokens to ~/.smokeball-mcp/tokens.json.

Verify the connection:

uv run --locked smokeball-mcp-verify

Verify checks the stored configuration, signs in to Smokeball, and reads the firm profile and up to five matters.

The server reads these environment variables. A variable set in the process environment takes precedence over a stored value.

Variable

Required

Default

Purpose

SMOKEBALL_CLIENT_ID

Yes

Stored value from setup

Smokeball OAuth client ID.

SMOKEBALL_CLIENT_SECRET

Yes

Stored value from setup

Smokeball OAuth client secret.

SMOKEBALL_API_KEY

Yes

Stored value from setup

Smokeball partner API key, sent as the x-api-key header.

SMOKEBALL_REGION

No

us

us, au or uk. Any other value is rejected at startup (see Regions).

SMOKEBALL_MCP_USE_KEYRING

No

1

Set to 0 (or false, no, off) to skip the OS keyring and use the .env file fallback.

SMOKEBALL_ALLOWED_DESTINATION_HOSTS

Only for webhook and plugin tools that take a URL

unset

Comma-separated hosts approved as webhook and plugin destinations (see Approved destination URLs).

Usage with Claude Desktop

Add the server to Claude Desktop's configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "smokeball": {
      "command": "uv",
      "args": ["run", "--locked", "--directory", "/absolute/path/to/smokeball-mcp", "smokeball-mcp"]
    }
  }
}

Replace /absolute/path/to/smokeball-mcp with the path of your clone. Restart Claude Desktop after saving. Any other stdio MCP client uses the same command and arguments.

HTTP mode

Stdio is the default. Set SMOKEBALL_MCP_TRANSPORT=streamable-http to serve the stateless Streamable HTTP transport from MCP specification 2026-07-28 at /mcp. Each request stands alone: no initialization handshake and no Mcp-Session-Id. Clients on earlier protocol versions are served on the same endpoint.

Security: this endpoint has no authentication and no TLS. Anyone who can reach the port can run every tool, including write and delete tools, with this server's vendor credentials. Keep the default loopback bind (127.0.0.1), or put the server behind an authenticating TLS proxy on a private network. SMOKEBALL_MCP_ALLOWED_HOSTS and SMOKEBALL_MCP_ALLOWED_ORIGINS protect against browser DNS rebinding, not against direct callers. A proxy in front of it needs connection and idle timeouts: a legacy-style GET /mcp with Accept: text/event-stream holds a stream open until the client disconnects.

Variable

Default

Purpose

SMOKEBALL_MCP_TRANSPORT

stdio

stdio or streamable-http. A set but empty value selects stdio.

SMOKEBALL_MCP_HOST

127.0.0.1

Bind address. 127.0.0.1, localhost and ::1 use the SDK's built-in Host and Origin checks; any other value requires SMOKEBALL_MCP_ALLOWED_HOSTS.

PORT

8080

Port; must be an integer.

SMOKEBALL_MCP_ALLOWED_HOSTS

unset

Comma-separated Host header values accepted on a non-loopback bind, such as mcp.example.com:8080 or mcp.example.com:*.

SMOKEBALL_MCP_ALLOWED_ORIGINS

unset

Comma-separated Origin values accepted on a non-loopback bind, such as https://client.example.com. Requests without an Origin header are accepted; with this unset on a non-loopback bind, a request that carries an Origin header is rejected.

Smokeball credentials come from the same configuration as stdio (see Configuration), never from the request.

SMOKEBALL_MCP_TRANSPORT=streamable-http PORT=8080 uv run --locked smokeball-mcp

Point the MCP client at http://127.0.0.1:8080/mcp. Responses use the SDK's default SSE behavior, so a client disconnect cancels the request.

Error handling

A failed tool call returns an MCP error result (isError) with a fixed message. The server never passes a Smokeball response body, a request URL or a credential back to the client. Failures raised while a tool runs start with Error executing tool <name>: .

Situation

What the tool returns

Credentials or OAuth tokens missing

"Smokeball credentials are missing." or "Smokeball OAuth tokens are missing.", followed by the variables to set and the instruction to run smokeball-mcp-setup and restart the MCP server.

HTTP 401 (after one automatic token refresh)

"Smokeball authorization was rejected or expired. Re-authorize with: smokeball-mcp-setup"

HTTP 403

"Smokeball access denied: the connected account lacks permission for this action (or the authorization expired; re-run smokeball-mcp-setup if so)."

HTTP 404

"The requested item was not found (HTTP 404). Check the ID and try again."

HTTP 429

"Smokeball rate limit exceeded (HTTP 429). Retry after N seconds." N comes from the Retry-After header, or is 10 when the header is missing or unusable.

Other HTTP error statuses

"Smokeball API request failed (HTTP 500)." followed by one fixed sentence. By default the sentence depends on the status: "The request was rejected." (400), "The request conflicts with the current item state." (409), "The request fields were rejected." (422), "The service had an internal error." (500), "The service is temporarily unavailable." (502 and 503), "The service timed out." (504), or "The request failed." for any other status. When the Smokeball response body carries a recognized error code, the sentence for that code is used instead: "The request is invalid." (invalid_request), "Request validation failed." (validation_error), "A request parameter is invalid." (invalid_parameter), "The request conflicts with the current item state." (conflict) or "The service is temporarily unavailable." (service_unavailable). A successful response that is not valid JSON returns "The service returned invalid JSON."

Timeout or connection failure on a read

"Smokeball could not be reached. Check the connection and retry."

Timeout or connection failure on a write

"Smokeball request outcome is unknown. Check whether it completed before retrying."

Webhook or plugin URL not approved

"Invalid argument target_url: expected a public HTTPS URL approved by SMOKEBALL_ALLOWED_DESTINATION_HOSTS."

Invalid arguments

A message that names the argument and the shape it expects, such as "Invalid arguments: matter_id must be a required string".

Anything else

Error executing tool <name> with no detail.

Every Smokeball request has a 30-second timeout and redirects are not followed. On HTTP 401 the server refreshes the OAuth access token once and repeats the request. On HTTP 429 it waits for the Retry-After period (10 seconds when absent) and retries up to 3 times, as long as no single wait is over 60 seconds and the waits together stay within 60 seconds; otherwise it returns the rate-limit message. Other failures are not retried.

Missing credentials do not stop the server from starting: each tool call reports them. At startup the server exits with a message and a non-zero status when SMOKEBALL_MCP_TRANSPORT is neither stdio nor streamable-http, when PORT is not an integer, or when a non-loopback SMOKEBALL_MCP_HOST is set without SMOKEBALL_MCP_ALLOWED_HOSTS. An unsupported SMOKEBALL_REGION also stops the server at startup.

Regions

Region

API Base

US

api.smokeball.com

AU

api.smokeball.com.au

UK

api.smokeball.co.uk

Region is set during setup and stored securely (OS keyring or ~/.smokeball-mcp/.env fallback). SMOKEBALL_REGION is trimmed and lowercased before validation. It accepts only us, au, or uk. Setup also accepts the corresponding menu numbers. Unknown values fail; they never select US.

Credential storage

By default credentials are stored in your operating system's native secret store via the cross-platform keyring library:

OS

Backend

macOS

Keychain

Windows

Credential Manager

Linux

Secret Service (GNOME Keyring / KWallet)

Secrets are saved under the service name smokeball-mcp. With a working keyring backend, credentials are not written to the file fallback.

File fallback. On a host with no keyring backend (e.g. a headless Linux box without Secret Service), or if you set SMOKEBALL_MCP_USE_KEYRING=0, credentials fall back to a ~/.smokeball-mcp/.env file with 0600 permissions.

On Windows, the file is stored in the user's profile and protected by Windows' default per-user access rules. On POSIX, files are created with 0600 permissions and writes fail closed if private permissions cannot be established.

Read order. A credential already present in the server process environment takes precedence, including one set in your MCP client's configuration. Otherwise the server checks the OS keyring, then the .env file. If you change credentials after the server has loaded them, restart the MCP server to reload the new values.

Authentication

Smokeball uses two credential layers:

  • OAuth 2.0 Bearer token — user identity, obtained via auth code flow

  • x-api-key header — app/partner identity, static key from Smokeball partner portal

Both are required for every API call. The setup wizard handles both.

Example usage in Claude

"List my open matters"

"Create a task on matter abc-123 due next Friday — prepare hearing brief"

"Add a fee entry for 2.5 hours on the Johnson matter, description: drafted motion to dismiss"

"Show me all trust account transactions for the Smith matter"

"Send a portal message to the client on matter xyz-456 — documents are ready for review"

Approved destination URLs

Set SMOKEBALL_ALLOWED_DESTINATION_HOSTS in the server environment, for example SMOKEBALL_ALLOWED_DESTINATION_HOSTS=hooks.firm.example,.integrations.firm.example. Comma-separated exact hosts allow only that host; a leading dot allows the domain and its subdomains. Matching ignores case and trailing dots and normalizes IDNA. An empty or unset list refuses destination URLs before any request. HTTPS, no userinfo, and public literal addresses remain required. This administrator-owned list prevents model-supplied destinations from sending data to arbitrary hosts, including private-address DNS aliases and unapproved redirectors. Approve only hosts whose DNS and redirects the firm trusts; the vendor executes requests later. Tools cannot change this setting. The list applies to the URL argument of create_webhook_subscription, update_webhook_subscription, create_plugin and update_plugin.

Testing

The test suite runs offline and needs no Smokeball account: Smokeball API calls are replaced with test doubles, and credentials come from inert test values with the OS keyring disabled. It covers the error messages tools return, argument validation, path identifier handling, the OAuth setup callback and credential storage including private file permissions, the webhook and plugin destination allowlist, the setup and verify command help, MCP specification 2026-07-28 behavior, and the Streamable HTTP transport including Host and Origin checks and stateless requests.

uv sync --locked
uv run --locked pytest -q

CI runs the suite on every push and pull request to main.

License

MIT. See LICENSE.

Available Tools

189 tools
add_contact_tagsC

Add tags to a contact. tags_csv: comma-separated tag strings.

Inputs: tags_csv (required), contact_id (required). Returns: result

add_contact_to_layoutC

Add a contact to a layout instance (for merge field population).

Inputs: layout_id (required), matter_id (required), contact_id (required), role. Returns: result

add_files_to_matter_batchA

Add multiple files to a matter in one request. files_csv: comma-separated file names.

Inputs: files_csv (required), matter_id (required). Returns: result

add_file_to_matterB

Register a new file on a matter (get upload URL separately).

Inputs: name (required), matter_id (required), folder_id. Returns: result

add_layout_to_matterA

Add a layout design instance to a matter for document generation.

Inputs: matter_id (required), layout_design_id (required). Returns: result

add_matter_tagsB

Add tags to a matter. tags_json: JSON array of tag objects, each with keys: id (str), name (str), color (str), type (str). Example: [{"id": "abc", "name": "Urgent", "color": "red", "type": "custom"}]

Inputs: matter_id (required), tags_json (required). Returns: result

add_relationship_to_roleC

Add a contact relationship to a role on a matter.

Inputs: role_id (required), matter_id (required), contact_id (required), relation_type. Returns: result

add_role_to_matterC

Add a role to a matter. contact_id: associate a contact to this role.

Inputs: matter_id (required), role_name (required), contact_id. Returns: result

archive_matterD

Archive a matter.

Inputs: matter_id (required), reason. Returns: result

create_activity_codeC

Create a billing activity code.

Inputs: code (required), description (required), rate. Returns: result

create_authorization_groupC

Create an authorization group.

Inputs: name (required), description. Returns: result

create_authorization_policyC

Create an authorization policy. permissions_csv: comma-separated permission strings.

Inputs: name (required), permissions_csv (required). Returns: result

create_contactB

Create a contact. contact_type: 'person' (default) or 'company'. For person: supply first_name / last_name. For company: supply company_name.

Inputs: email, phone, last_name, first_name, +2 more. Returns: result

create_contact_relationC

Create a relationship between two contacts.

Inputs: contact_id (required), related_contact_id (required), relation_type. Returns: result

create_eventB

Create a calendar event. start_date/end_date: ISO 8601 datetime.

Inputs: name (required), start_date (required), notes, end_date, +2 more. Returns: result

create_event_reminderC

Create a reminder for an event. reminder_type: Notification | Email.

Inputs: event_id (required), minutes_before (required), reminder_type. Returns: result

create_expenseC

Create an expense entry. date: YYYY-MM-DD. amount: dollar value. billable: 'true' (default) or 'false'.

Inputs: date (required), amount (required), matter_id (required), billable, +2 more. Returns: result

create_feeC

Create a fee (time entry). date: YYYY-MM-DD. duration_minutes: time spent. billable: 'true' (default) or 'false'.

Inputs: date (required), staff_id (required), matter_id (required), duration_minutes (required), +4 more. Returns: result

create_file_preview_requestC

Request generation of a preview (thumbnail/rendition) for a file.

Inputs: file_id (required). Returns: result

create_folderB

Create a folder in a matter. parent_folder_id: omit for root.

Inputs: name (required), matter_id (required), parent_folder_id. Returns: result

create_leadA

Create a lead (created as a matter with isLead=true via POST /matters). matter_type_id: from list_matter_types. client_id: existing contact ID to associate as client.

Inputs: client_id, matter_type_id. Returns: result

create_matterC

Create a matter. matter_type_id: from list_matter_types (required). client_ids_csv: comma-separated contact IDs to set as clients (required). number: optional matter reference number.

Inputs: client_ids_csv (required), matter_type_id (required), number, status, +1 more. Returns: result

create_memoC

Create a memo (note) on a matter.

Inputs: content (required), matter_id (required), subject. Returns: result

create_notificationC

Send a notification to a user or the firm.

Inputs: title (required), message (required), user_id. Returns: result

create_pluginC

Register a new plugin integration.

Inputs: url (required), name (required), description. Returns: result

create_portal_taskB

Create a client portal task (visible to client). due_date: YYYY-MM-DD.

Inputs: title (required), matter_id (required), due_date, contact_id, +1 more. Returns: result

create_requisitionC

Create a trust fund requisition (draw-down request).

Inputs: amount (required), matter_id (required), account_id (required), payee, +1 more. Returns: result

create_staff_memberC

Create a new staff member.

Inputs: email (required), last_name (required), first_name (required), role. Returns: result

create_subtaskC

Create a subtask under a task.

Inputs: name (required), task_id (required), due_date. Returns: result

create_taskC

Create a task. due_date: ISO 8601 (YYYY-MM-DD). assigned_to_id: staff ID.

Inputs: name (required), notes, due_date, matter_id, +1 more. Returns: result

create_task_documentC

Attach a file to a task. file_id: from files API.

Inputs: file_id (required), task_id (required), name. Returns: result

create_transactionB

Create a bank account transaction. amount: positive for deposit, negative for withdrawal.

Inputs: amount (required), matter_id (required), account_id (required), description, +1 more. Returns: result

create_userC

Create a new user (invite to the firm).

Inputs: email (required), last_name, first_name. Returns: result

create_webhook_subscriptionC

Create a webhook subscription. event_type: from list_webhook_event_types.

Inputs: url (required), event_type (required), secret. Returns: result

delete_activity_codeC

Delete an activity code by ID.

Inputs: code_id (required). Returns: result

delete_authorization_groupC

Delete an authorization group by ID.

Inputs: group_id (required). Returns: result

delete_contactC

Delete a contact by ID.

Inputs: contact_id (required). Returns: result

delete_contact_relationB

Delete a relationship from a contact.

Inputs: contact_id (required), relation_id (required). Returns: result

delete_eventC

Delete a calendar event by ID.

Inputs: event_id (required). Returns: result

delete_event_reminderC

Delete an event reminder.

Inputs: event_id (required), reminder_id (required). Returns: result

delete_expenseC

Delete an expense entry by ID.

Inputs: expense_id (required). Returns: result

delete_feeB

Delete a fee entry by ID.

Inputs: fee_id (required). Returns: result

delete_fileC

Delete a file by ID.

Inputs: file_id (required). Returns: result

delete_firm_user_mappingC

Delete a firm user mapping by ID.

Inputs: mapping_id (required). Returns: result

delete_folderC

Delete a folder by ID.

Inputs: folder_id (required). Returns: result

delete_leadC

Delete a lead by ID.

Inputs: lead_id (required). Returns: result

delete_matterC

Delete a matter by ID.

Inputs: matter_id (required). Returns: result

delete_memoC

Delete a memo by ID.

Inputs: memo_id (required). Returns: result

delete_pluginC

Delete a plugin by ID.

Inputs: plugin_id (required). Returns: result

delete_staff_memberC

Delete a staff member by ID.

Inputs: staff_id (required). Returns: result

delete_subtaskC

Delete a subtask.

Inputs: task_id (required), subtask_id (required). Returns: result

delete_taskC

Delete a task by ID.

Inputs: task_id (required). Returns: result

delete_task_documentB

Remove a document attachment from a task.

Inputs: task_id (required), document_id (required). Returns: result

delete_webhook_subscriptionB

Delete a webhook subscription by ID.

Inputs: subscription_id (required). Returns: result

get_activity_codeC

Get an activity code by ID.

Inputs: code_id (required). Returns: result

get_authorization_groupB

Get an authorization group by ID.

Inputs: group_id (required). Returns: result

get_authorization_policyC

Get an authorization policy by reference.

Inputs: reference (required). Returns: result

get_bank_accountC

Get a bank account by ID.

Inputs: account_id (required). Returns: result

get_bank_account_matter_balancesB

Get per-matter balances for a bank account (trust accounting).

Inputs: account_id (required). Returns: result

get_contactC

Get a contact by ID.

Inputs: contact_id (required). Returns: result

get_contact_relationB

Get a specific relationship for a contact.

Inputs: contact_id (required), relation_id (required). Returns: result

get_contact_relationsC

Get all relationships for a contact.

Inputs: contact_id (required). Returns: result

get_contact_tagsB

Get tags on a contact.

Inputs: contact_id (required). Returns: result

get_eventB

Get a calendar event by ID.

Inputs: event_id (required). Returns: result

get_event_remindersB

Get all reminders for a calendar event.

Inputs: event_id (required). Returns: result

get_expenseC

Get an expense entry by ID.

Inputs: expense_id (required). Returns: result

get_feeB

Get a fee entry by ID.

Inputs: fee_id (required). Returns: result

get_fileB

Get file metadata by ID.

Inputs: file_id (required). Returns: result

get_file_download_urlB

Get a pre-signed download URL for a file.

Inputs: file_id (required). Returns: result

get_file_historyC

Get file version history for a matter.

Inputs: matter_id (required), limit, offset. Returns: result

get_file_preview_infoB

Get preview info (status and URL) for a file.

Inputs: file_id (required). Returns: result

get_file_preview_info_by_versionB

Get preview info for a specific version of a file.

Inputs: file_id (required), version_id (required). Returns: result

get_file_upload_urlB

Get a pre-signed upload URL for a file version.

Inputs: file_id (required). Returns: result

get_firmA

Get this firm's profile and settings.

Inputs: no named parameters. Returns: result

get_firm_user_mappingB

Get a specific firm user mapping by ID.

Inputs: mapping_id (required). Returns: result

get_firm_user_mappingsA

List all user mappings for this firm.

Inputs: no named parameters. Returns: result

get_folder_contentsC

Get the contents of a specific folder on a matter.

Inputs: folder_id (required), matter_id (required). Returns: result

get_folder_historyC

Get folder activity history for a matter.

Inputs: matter_id (required), limit, offset. Returns: result

get_folder_path_hierarchyC

Get the full path hierarchy (breadcrumb) to a folder.

Inputs: folder_id (required), matter_id (required). Returns: result

get_invoiceC

Get an invoice by ID.

Inputs: invoice_id (required). Returns: result

get_invoice_download_urlC

Get a download URL for an invoice PDF.

Inputs: invoice_id (required). Returns: result

get_layout_contactsC

Get contacts associated with a layout instance.

Inputs: layout_id (required), matter_id (required). Returns: result

get_layout_designA

Get a layout design by ID.

Inputs: design_id (required). Returns: result

get_layout_on_matterB

Get a specific layout instance on a matter.

Inputs: layout_id (required), matter_id (required). Returns: result

get_leadC

Get a lead by ID.

Inputs: lead_id (required). Returns: result

get_matterB

Get a matter by ID.

Inputs: matter_id (required). Returns: result

get_matter_archiveC

Get archive status and metadata for a matter.

Inputs: matter_id (required). Returns: result

get_matter_billing_configurationB

Get billing configuration for a matter.

Inputs: matter_id (required). Returns: result

get_matter_itemC

Get a specific item on a matter.

Inputs: item_id (required), matter_id (required). Returns: result

get_matter_stageB

Get the current stage of a matter.

Inputs: matter_id (required). Returns: result

get_matter_tagsC

Get tags on a matter.

Inputs: matter_id (required). Returns: result

get_matter_typeB

Get a matter type by ID.

Inputs: matter_type_id (required). Returns: result

get_memoB

Get a memo by ID.

Inputs: memo_id (required). Returns: result

get_notificationB

Get a notification by ID.

Inputs: notification_id (required). Returns: result

get_pluginC

Get a plugin by ID.

Inputs: plugin_id (required). Returns: result

get_plugin_subscriptionA

Get a specific plugin subscription by ID.

Inputs: subscription_id (required). Returns: result

get_plugin_urlB

Request the launch URL for a plugin (for embedded iframe display).

Inputs: plugin_id (required). Returns: result

get_protected_bank_account_balanceC

Get the protected (reserved) balance for a bank account.

Inputs: account_id (required). Returns: result

get_referral_typeC

Get a referral type by ID.

Inputs: referral_type_id (required). Returns: result

get_relationship_on_roleC

Get the contact relationship for a specific role on a matter.

Inputs: role_id (required), matter_id (required). Returns: result

get_relationships_on_matterC

Get all contact relationships on a matter.

Inputs: matter_id (required). Returns: result

get_role_on_matterB

Get a specific role on a matter.

Inputs: role_id (required), matter_id (required). Returns: result

get_roles_on_matterB

List all roles assigned to a matter.

Inputs: matter_id (required). Returns: result

get_root_folder_contentsC

Get the root folder contents for a matter.

Inputs: matter_id (required). Returns: result

get_search_mappingA

Get the integrated search field mapping (what fields are indexed for search).

Inputs: no named parameters. Returns: result

get_staff_memberB

Get a staff member by ID.

Inputs: staff_id (required). Returns: result

get_stage_in_setC

Get a specific stage within a stage set.

Inputs: stage_id (required), stage_set_id (required). Returns: result

get_stage_setB

Get a specific stage set by ID.

Inputs: stage_set_id (required). Returns: result

get_subtaskC

Get a specific subtask.

Inputs: task_id (required), subtask_id (required). Returns: result

get_subtasksC

Get all subtasks for a task.

Inputs: task_id (required). Returns: result

get_taskC

Get a task by ID.

Inputs: task_id (required). Returns: result

get_task_documentC

Get a specific document attached to a task.

Inputs: task_id (required), document_id (required). Returns: result

get_task_documentsC

Get documents attached to a task.

Inputs: task_id (required). Returns: result

get_transactionC

Get a specific transaction from a bank account.

Inputs: account_id (required), transaction_id (required). Returns: result

get_userC

Get a user by ID.

Inputs: user_id (required). Returns: result

get_webhook_subscriptionB

Get a webhook subscription by ID.

Inputs: subscription_id (required). Returns: result

list_activity_codesC

List billing activity codes configured for this firm.

Inputs: limit, offset. Returns: result

list_authorization_groupsA

List all authorization groups for this firm.

Inputs: no named parameters. Returns: result

list_bank_accountsB

List bank accounts (trust, operating) for this firm.

Inputs: limit, offset. Returns: result

list_contactsC

List contacts with offset pagination.

Inputs: limit, offset. Returns: result

list_eventsB

List calendar events. Filter by matter_id for matter-specific events.

Inputs: limit, offset, matter_id. Returns: result

list_expensesC

List expense entries. Filter by matter_id for matter-specific expenses.

Inputs: limit, offset, matter_id. Returns: result

list_feesB

List fee entries (billable time). Filter by matter_id for matter-specific fees.

Inputs: limit, offset, matter_id. Returns: result

list_files_on_matterC

List files attached to a matter.

Inputs: matter_id (required), limit, offset. Returns: result

list_invoicesB

List invoices. Filter by matter_id for matter-specific invoices.

Inputs: limit, offset, matter_id. Returns: result

list_layout_designsA

List all layout designs (document templates) available for this firm.

Inputs: no named parameters. Returns: result

list_layouts_on_matterB

List all layout instances on a matter (document merge records).

Inputs: matter_id (required). Returns: result

list_leadsC

List leads (potential new clients/matters).

Inputs: limit, offset. Returns: result

list_matter_itemsB

List all items (checklist items, workflow steps) on a matter.

Inputs: matter_id (required). Returns: result

list_mattersC

List matters with offset pagination.

Inputs: limit, offset. Returns: result

list_matter_stage_mappingsA

List all matter-to-stage mappings.

Inputs: no named parameters. Returns: result

list_matter_type_categoriesB

List all matter type categories.

Inputs: no named parameters. Returns: result

list_matter_typesB

List all matter types configured for this firm.

Inputs: limit, offset. Returns: result

list_memos_on_matterC

List memos (notes) on a matter.

Inputs: matter_id (required), limit, offset. Returns: result

list_pluginsA

List all available plugins for this firm.

Inputs: no named parameters. Returns: result

list_plugin_subscriptionsA

List all active plugin subscriptions for this firm.

Inputs: no named parameters. Returns: result

list_referral_typesC

List referral source types configured for this firm.

Inputs: limit, offset. Returns: result

list_stage_setsB

List all stage sets (workflow stage groups).

Inputs: no named parameters. Returns: result

list_tasksC

List tasks. Filter by matter_id to get matter-specific tasks.

Inputs: limit, offset, matter_id. Returns: result

list_transactionsC

List transactions for a bank account.

Inputs: account_id (required), limit, offset. Returns: result

list_webhook_event_typesA

List all available webhook event types.

Inputs: no named parameters. Returns: result

list_webhook_subscriptionsA

List all active webhook subscriptions.

Inputs: no named parameters. Returns: result

merge_layoutB

Execute a layout merge (generate the document from template + matter data).

Inputs: layout_id (required), matter_id (required). Returns: result

patch_expenseA

Toggle an expense entry's billable or billed state (PATCH). Use 'true' or 'false'.

Inputs: expense_id (required), billed, billable. Returns: result

patch_feeC

Toggle a fee entry's billable or billed state (PATCH). Use 'true' or 'false'.

Inputs: fee_id (required), billed, billable. Returns: result

patch_fileC

Update file metadata (name, folder).

Inputs: file_id (required), name, folder_id. Returns: result

patch_folderB

Move a folder to a different parent.

Inputs: folder_id (required), parent_folder_id. Returns: result

patch_leadA

Partially update a lead status or assignment (PATCH). Use update_lead for notes.

Inputs: lead_id (required), status, assigned_to_id. Returns: result

patch_matterA

Partially update a matter status or stage (PATCH). Use update_matter for name/description.

Inputs: matter_id (required), status, stage_id. Returns: result

patch_matter_archiveC

Update archive metadata fields on a matter (PATCH). destruction_date: YYYY-MM-DD.

Inputs: matter_id (required), destruction_date, retention_policy. Returns: result

protect_fundsB

Protect (reserve) funds in a trust account for a matter.

Inputs: amount (required), matter_id (required), account_id (required), reason. Returns: result

remove_contact_tagsC

Remove a tag from a contact. tag_id: the ID of the tag to remove.

Inputs: tag_id (required), contact_id (required). Returns: result

remove_layout_from_matterC

Remove a layout instance from a matter.

Inputs: layout_id (required), matter_id (required). Returns: result

remove_matter_tagsB

Remove a tag from a matter. tag_id: the ID of the tag to remove.

Inputs: tag_id (required), matter_id (required). Returns: result

remove_relationship_from_roleC

Remove a contact relationship from a role on a matter.

Inputs: role_id (required), matter_id (required), relationship_id (required). Returns: result

remove_role_from_matterB

Remove a role from a matter.

Inputs: role_id (required), matter_id (required). Returns: result

remove_userB

Remove a user from the firm.

Inputs: user_id (required). Returns: result

resend_user_invitationB

Resend an invitation email to a user.

Inputs: user_id (required). Returns: result

search_staffC

Search staff members. query: name or email fragment.

Inputs: limit, query, offset. Returns: result

send_portal_messageC

Send a message to a client via the Smokeball client portal.

Inputs: message (required), matter_id (required), contact_id. Returns: result

subscribe_to_pluginC

Subscribe this firm to a plugin.

Inputs: plugin_id (required). Returns: result

test_webhook_subscriptionB

Send a test notification to a webhook subscription endpoint.

Inputs: subscription_id (required). Returns: result

unarchive_matterC

Unarchive a matter.

Inputs: matter_id (required). Returns: result

unprotect_fundsB

Release protected (reserved) funds back to available balance.

Inputs: amount (required), matter_id (required), account_id (required). Returns: result

unsubscribe_from_pluginC

Unsubscribe this firm from a plugin.

Inputs: plugin_id (required). Returns: result

update_activity_codeC

Update an activity code.

Inputs: code_id (required), code, rate, description. Returns: result

update_authorization_groupC

Update an authorization group.

Inputs: group_id (required), name, description. Returns: result

update_authorization_policyC

Update an authorization policy. permissions_csv: comma-separated permission strings.

Inputs: reference (required), name, permissions_csv. Returns: result

update_contactC

Update a contact's details.

Inputs: contact_id (required), email, phone, last_name, +1 more. Returns: result

update_contact_relationC

Update a contact relationship type.

Inputs: contact_id (required), relation_id (required), relation_type (required). Returns: result

update_eventC

Update a calendar event.

Inputs: event_id (required), name, end_date, location, +1 more. Returns: result

update_event_reminderB

Update an event reminder's lead time.

Inputs: event_id (required), reminder_id (required), minutes_before (required). Returns: result

update_expenseC

Update an expense entry. billable: 'true' or 'false' to set; leave empty to skip.

Inputs: expense_id (required), amount, billable, description. Returns: result

update_feeC

Update a fee entry. billable: 'true' or 'false' to set; leave empty to skip.

Inputs: fee_id (required), rate, billable, description, +1 more. Returns: result

update_firmA

Update firm profile fields. Only pass fields you want to change.

Inputs: name, email, phone, address. Returns: result

update_firm_user_mappingC

Update a firm user mapping (link a staff member to a system user).

Inputs: mapping_id (required), email, staff_id. Returns: result

update_folderC

Rename a folder.

Inputs: name (required), folder_id (required). Returns: result

update_leadC

Update a lead's status or notes.

Inputs: lead_id (required), notes, status. Returns: result

update_matterC

Update a matter's name, status, or description.

Inputs: matter_id (required), name, status, description. Returns: result

update_matter_billing_configurationC

Update billing configuration for a matter. billing_type: Hourly | Fixed | Contingency.

Inputs: matter_id (required), rate, billing_type. Returns: result

update_memoB

Update a memo's content or subject.

Inputs: memo_id (required), content, subject. Returns: result

update_pluginC

Update a plugin's details.

Inputs: plugin_id (required), url, name. Returns: result

update_portal_taskC

Update a client portal task status or title. completed_str: 'true' or 'false'.

Inputs: task_id (required), title, completed_str. Returns: result

update_relationshipC

Update a contact relationship on a matter role.

Inputs: role_id (required), matter_id (required), relation_type (required), relationship_id (required). Returns: result

update_role_on_matterC

Update a role on a matter.

Inputs: role_id (required), matter_id (required), contact_id. Returns: result

update_staff_memberC

Update a staff member's details.

Inputs: staff_id (required), role, email, last_name, +1 more. Returns: result

update_subtaskC

Update a subtask. completed_str: 'true' to mark done, 'false' to unmark.

Inputs: task_id (required), subtask_id (required), name, completed_str. Returns: result

update_taskD

Update a task. completed_str: 'true' to mark done, 'false' to unmark.

Inputs: task_id (required), name, notes, due_date, +1 more. Returns: result

update_webhook_subscriptionA

Update a webhook subscription URL or active state. active: 'true' or 'false'.

Inputs: subscription_id (required), url, active. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 189 tools

    Disambiguation4/5

    Most tools target distinct entities and actions, but the split between patch/update for matters and leads could confuse an agent. Also, similar verbs like 'remove' vs 'delete' are used interchangeably, though descriptions clarify differences.

    Naming Consistency4/5

    Tools largely follow a verb_noun pattern (create_, get_, list_, update_, delete_), but there are inconsistencies: 'remove_' instead of 'delete_' for tags and relationships, and occasional non-parallel verbs like 'archive_matter' vs 'unarchive_matter'.

    Tool Count2/5

    With 189 tools, the server is excessively large for a typical MCP server. While the domain (legal practice management) is broad, many operations could be consolidated or parameterized. This number overwhelms agents and reduces usability.

    Completeness3/5

    The tool surface covers CRUD for most entities (contacts, matters, tasks, fees, etc.) and includes many auxiliary features (tags, roles, layouts, webhooks). However, there are notable gaps: no search tools for matters or contacts (only list with pagination), and batch operations are limited.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server that connects Clio Manage to Claude via OAuth, enabling law firm management tasks like matter lookup, time tracking, billing, calendar, and document retrieval through natural language.
      41
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      MCP server for Bill4Time providing API coverage for legal billing and time tracking, enabling natural language interaction with clients, projects, time entries, invoices, payments, and more from Claude Desktop.
      59
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for Clio Manage that enables interaction with legal practice data including matters, contacts, activities, communications, tasks, documents, calendar entries, and bills via natural language.
      Apache 2.0