smokeball-mcp
Manage Smokeball law firm practice management data via MCP tools for firm/staff/users, contacts/leads, matters/workflows, tasks/events, memos, and billing entries.
Firm profile and user mappings: view/update firm details, manage staff-to-user mappings
Staff and users: search/get/create/update/delete staff; invite/remove/resend user invitations
Contacts: CRUD contacts, manage contact relations and tags
Leads: list/get/create/update/patch/delete leads
Matters: CRUD matters, patch status/stage, manage billing configuration and tags
Matter types/categories and stage sets: inspect matter types, categories, stage sets, stages, and matter-stage mappings
Matter roles and relationships: assign/update/remove roles and contact relationships on matters
Tasks: CRUD tasks and subtasks, attach/remove task documents
Events: CRUD calendar events, manage reminders
Memos: list/get/create/update/delete matter memos
Billing: list/get/create/update/patch/delete fees/time entries; list/get/create expenses
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@smokeball-mcp List my open matters"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Smokeball MCP server
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_tagsadd_contact_to_layoutadd_file_to_matteradd_files_to_matter_batchadd_layout_to_matteradd_matter_tagsadd_relationship_to_roleadd_role_to_matterarchive_mattercreate_activity_codecreate_authorization_groupcreate_authorization_policycreate_contactcreate_contact_relationcreate_eventcreate_event_remindercreate_expensecreate_feecreate_file_preview_requestcreate_foldercreate_leadcreate_mattercreate_memocreate_notificationcreate_plugincreate_portal_taskcreate_requisitioncreate_staff_membercreate_subtaskcreate_taskcreate_task_documentcreate_transactioncreate_usercreate_webhook_subscriptiondelete_activity_codedelete_authorization_groupdelete_contactdelete_contact_relationdelete_eventdelete_event_reminderdelete_expensedelete_feedelete_filedelete_firm_user_mappingdelete_folderdelete_leaddelete_matterdelete_memodelete_plugindelete_staff_memberdelete_subtaskdelete_taskdelete_task_documentdelete_webhook_subscriptionget_activity_codeget_authorization_groupget_authorization_policyget_bank_accountget_bank_account_matter_balancesget_contactget_contact_relationget_contact_relationsget_contact_tagsget_eventget_event_remindersget_expenseget_feeget_fileget_file_download_urlget_file_historyget_file_preview_infoget_file_preview_info_by_versionget_file_upload_urlget_firmget_firm_user_mappingget_firm_user_mappingsget_folder_contentsget_folder_historyget_folder_path_hierarchyget_invoiceget_invoice_download_urlget_layout_contactsget_layout_designget_layout_on_matterget_leadget_matterget_matter_archiveget_matter_billing_configurationget_matter_itemget_matter_stageget_matter_tagsget_matter_typeget_memoget_notificationget_pluginget_plugin_subscriptionget_plugin_urlget_protected_bank_account_balanceget_referral_typeget_relationship_on_roleget_relationships_on_matterget_role_on_matterget_roles_on_matterget_root_folder_contentsget_search_mappingget_staff_memberget_stage_in_setget_stage_setget_subtaskget_subtasksget_taskget_task_documentget_task_documentsget_transactionget_userget_webhook_subscriptionlist_activity_codeslist_authorization_groupslist_bank_accountslist_contactslist_eventslist_expenseslist_feeslist_files_on_matterlist_invoiceslist_layout_designslist_layouts_on_matterlist_leadslist_matter_itemslist_matter_stage_mappingslist_matter_type_categorieslist_matter_typeslist_matterslist_memos_on_matterlist_plugin_subscriptionslist_pluginslist_referral_typeslist_stage_setslist_taskslist_transactionslist_webhook_event_typeslist_webhook_subscriptionsmerge_layoutpatch_expensepatch_feepatch_filepatch_folderpatch_leadpatch_matterpatch_matter_archiveprotect_fundsremove_contact_tagsremove_layout_from_matterremove_matter_tagsremove_relationship_from_roleremove_role_from_matterremove_userresend_user_invitationsearch_staffsend_portal_messagesubscribe_to_plugintest_webhook_subscriptionunarchive_matterunprotect_fundsunsubscribe_from_pluginupdate_activity_codeupdate_authorization_groupupdate_authorization_policyupdate_contactupdate_contact_relationupdate_eventupdate_event_reminderupdate_expenseupdate_feeupdate_firmupdate_firm_user_mappingupdate_folderupdate_leadupdate_matterupdate_matter_billing_configurationupdate_memoupdate_pluginupdate_portal_taskupdate_relationshipupdate_role_on_matterupdate_staff_memberupdate_subtaskupdate_taskupdate_webhook_subscription
Prompts and resources
The server also registers three prompts and three read-only resources.
Prompt | What it does |
| Morning briefing of open matters needing attention, overdue tasks and unbilled fees. |
| Triage a new or recently opened matter by checking its contacts, billing setup and key documents. Takes a |
| Summary of a matter's fees, expenses, invoices and outstanding balances. Takes a |
Resource | What it holds |
| The matter types configured in your Smokeball firm. |
| The billable activity codes configured in your Smokeball firm. |
| 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 --lockedReleases 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-setupSetup does four things:
Asks for your region (US, AU or UK).
Asks for your Client ID, Client Secret and API Key.
Opens your browser for Smokeball authorization and listens for the redirect at
http://127.0.0.1:8768/callback.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-verifyVerify 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 |
| Yes | Stored value from setup | Smokeball OAuth client ID. |
| Yes | Stored value from setup | Smokeball OAuth client secret. |
| Yes | Stored value from setup | Smokeball partner API key, sent as the |
| No |
|
|
| No |
| Set to |
| 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_HOSTSandSMOKEBALL_MCP_ALLOWED_ORIGINSprotect against browser DNS rebinding, not against direct callers. A proxy in front of it needs connection and idle timeouts: a legacy-styleGET /mcpwithAccept: text/event-streamholds a stream open until the client disconnects.
Variable | Default | Purpose |
|
|
|
|
| Bind address. |
|
| Port; must be an integer. |
| unset | Comma-separated |
| unset | Comma-separated |
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-mcpPoint 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 |
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 |
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." ( |
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 |
|
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 -qCI runs the suite on every push and pull request to main.
License
MIT. See LICENSE.
Available Tools
189 toolsadd_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
Scored across 189 tools
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.
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'.
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.
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
Related MCP Connectors
Law firm management MCP: manage cases, clients, tasks, calendar and documents via Claude AI.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Clio MCP server for ChatGPT, Claude and any AI agent: search matters, log time entry, create task, add matter note, create calendar entry and list bills in your own Clio account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Clio yourself; Cotlet does not store your password and you need no Clio API key. About the official Clio API: Yes. Clio has a REST API, the Clio Manage API v4, with OAuth 2.0 (checked 6 Nov 2026). Setup and FAQ: https://cotlet.dev/integrations/clio-api-mcp-server
Related MCP Servers
- AlicenseCqualityBmaintenanceMCP server for Filevine that enables natural language interaction with legal case management, including projects, contacts, tasks, documents, billing, and more via Claude Desktop.1005MIT
- AlicenseAqualityCmaintenanceMCP 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.41MIT
- AlicenseCqualityBmaintenanceMCP 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.591MIT
- AlicenseNot gradedqualityBmaintenanceMCP 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