Smokeball MCP Server
RosenAdvertising/smokeball-mcp
API completa do Smokeball para gestão de escritórios jurídicos via Claude
Ver no GitHubServidor MCP que integra o Smokeball, plataforma de gestão de escritórios de advocacia, ao Claude Desktop com cobertura completa da API. Permite criar e gerenciar casos, contatos, tarefas, documentos, faturamento e portais de cliente através de linguagem natural.
Instalação
npx convez-ai RosenAdvertising/smokeball-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Criar e atualizar casos jurídicos com automação de fluxo
- Gerenciar contatos, leads e pipeline de vendas
- Administrar tarefas, eventos e lembretes integrados
- Processar faturamento, honorários e contabilidade forense
Veredito

Integração robusta e bem-documentada para o ecossistema jurídico. Requer credenciais de parceiro Smokeball e Python 3.10+, mas oferece automação profissional completa de processos jurídicos críticos via MCP.
README
A tradução para o português deste README ainda está na fila.
smokeball-mcp
MCP server for Smokeball — full API coverage for law firm practice management. Use Smokeball from Claude Desktop with natural language.
What you can do
- Matters — create, update, archive, tag, billing config, roles, relationships, stages
- Contacts & Leads — full CRUD, relations, tags, lead pipeline
- Tasks & Events — tasks, subtasks, task documents, calendar events, reminders
- Files & Folders — upload, download, preview, folder hierarchy, version history
- Billing — fees (time entries), expenses, invoices, activity codes, bank accounts, trust accounting
- Portals — client portal tasks and messages
- Document generation — layout designs, merge workflows, matter items
- Administration — staff, users, authorization groups/policies, plugins, webhooks, notifications
Requirements
- Python 3.10+
- Claude Desktop (or any MCP-compatible client)
- Smokeball partner credentials (Client ID, Client Secret, API Key)
Smokeball partner access: API credentials are issued through the Smokeball partner/developer program. Contact your Smokeball account representative to request API access.
Installation
pip install smokeball-mcp
Setup
Run the guided OAuth setup:
smokeball-mcp-setup
This will:
- Ask for your region (US / AU / UK)
- Ask for your Client ID, Client Secret, and API Key
- Open the browser for Smokeball authorization
- Save credentials to
~/.smokeball-mcp/
Verify the connection:
smokeball-mcp-verify
Claude Desktop Configuration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"smokeball": {
"command": "smokeball-mcp"
}
}
}
Restart Claude Desktop. Smokeball tools will appear automatically.
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).
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. Nothing is written to
disk in clear text.
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.
Read order. Credentials resolve in the order OS keyring → process environment
→ .env file. So a rotated secret in the keyring always wins, and a
SMOKEBALL_CLIENT_ID / SMOKEBALL_API_KEY exported in your shell overrides the
file fallback without touching the keyring.
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"
Tools
Full coverage across 30 Smokeball API resource categories — 189 tools total.
License
MIT