Ploomes MCP Server — Read-Only

Servidor MCP (Model Context Protocol) que expõe somente operações de leitura (GET) da API do CRM Ploomes.

⚠️ Este servidor não possui permissão para alterar, incluir ou excluir dados. Todas as 49 ferramentas disponíveis são exclusivamente de consulta.

Pré-requisitos

Python 3.11+
Uma conta Ploomes com User-Key de API

Instalação

# Clone o repositório
git clone <url-do-repo>
cd ploomes-mcp-server

# Crie e ative um ambiente virtual (recomendado)
python -m venv .venv
.venv\Scripts\activate   # Windows
# source .venv/bin/activate  # Linux/Mac

# Instale as dependências
pip install -r requirements.txt

Configuração

Edite o arquivo .env na raiz do projeto:

# Chave de API do Ploomes (obrigatória)
PLOOMES_USER_KEY=sua-chave-aqui

# URL base da API (padrão: https://api2.ploomes.com)
PLOOMES_BASE_URL=https://api2.ploomes.com

# Limite de requisições simultâneas (padrão: 120)
PLOOMES_RATE_LIMIT=120

# Transporte MCP: stdio (padrão) ou http
MCP_TRANSPORT=stdio

# Porta para transporte HTTP (padrão: 3000)
MCP_HTTP_PORT=3000

Uso

Modo stdio (padrão — para Claude Desktop, Cursor, etc.)

python -m src.server

Modo HTTP

set MCP_TRANSPORT=http
python -m src.server

MCP Inspector (para desenvolvimento)

mcp dev src/server.py

Documentação Completa

🛠️ Guia de Configuração e Uso (docs/setup_guide.md): Passo a passo completo para configurar e usar no Claude Desktop, Antigravity IDE e Cursor, além de dicas de resolução de problemas.
📖 Guia Completo das Ferramentas (docs/tools_guide.md): Explicação detalhada de cada uma das 49 ferramentas, campos retornados, filtros OData e exemplos de prompts em linguagem natural.

Configuração Rápida

Claude Desktop

Adicione ao %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "ploomes-reader": {
      "command": "C:\\caminho\\para\\ploomes-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["-m", "src.server"],
      "cwd": "C:\\caminho\\para\\ploomes-mcp-server"
    }
  }
}

Cursor

Adicione ao .cursor/mcp.json:

{
  "mcpServers": {
    "ploomes-reader": {
      "command": "C:\\caminho\\para\\ploomes-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["-m", "src.server"],
      "cwd": "C:\\caminho\\para\\ploomes-mcp-server"
    }
  }
}

Antigravity IDE

Adicione às configurações de MCP (mcp.json):

{
  "mcpServers": {
    "ploomes-reader": {
      "command": "C:\\caminho\\para\\ploomes-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["-m", "src.server"],
      "cwd": "C:\\caminho\\para\\ploomes-mcp-server"
    }
  }
}

Tools Disponíveis (49)

#	Tool	Endpoint	Descrição
1	`get_account`	/Account	Informações da conta/empresa
2	`get_cities`	/Cities	Cidades
3	`get_countries`	/Cities/Countries	Países
4	`get_states`	/Cities/Countries/States	Estados
5	`get_contacts`	/Contacts	Clientes/contatos
6	`get_contacts_numbers_of_employees`	/Contacts/NumbersOfEmployees	Opções de nº funcionários
7	`get_contacts_origins`	/Contacts/Origins	Origens de clientes
8	`get_contacts_lines_of_business`	/Contacts/LinesOfBusiness	Linhas de negócio
9	`get_contacts_relationships`	/Contacts/Relationships	Tipos de relacionamento
10	`get_contacts_status`	/Contacts/Status	Status de clientes
11	`get_contacts_types`	/Contacts/Types	Tipos de clientes
12	`get_contacts_products`	/Contacts/Products	Produtos de clientes
13	`get_currencies`	/Currencies	Moedas
14	`get_deals`	/Deals	Negócios
15	`get_deals_stages`	/Deals/Stages	Etapas dos negócios
16	`get_deals_status`	/Deals/Status	Status dos negócios
17	`get_deals_loss_reasons`	/Deals/LossReasons	Motivos de perda
18	`get_deals_pipelines`	/Deals/Pipelines	Funis de negócios
19	`get_documents`	/Documents	Documentos
20	`get_document_templates`	/DocumentTemplates	Modelos de documentos
21	`get_departments`	/Departments	Departamentos
22	`get_fields`	/Fields	Campos (inclui customizados)
23	`get_fields_entities`	/Fields/Entities	Entidades do sistema
24	`get_fields_options_tables`	/Fields/OptionsTables	Tabelas de opções
25	`get_fields_options_tables_options`	/Fields/OptionsTables/Options	Opções das tabelas
26	`get_fields_types`	/Fields/Types	Tipos de campos
27	`get_interaction_records`	/InteractionRecords	Registros de interação
28	`get_operations`	/Operations	Operações
29	`get_orders`	/Orders	Vendas
30	`get_orders_stages`	/Orders/Stages	Etapas das vendas
31	`get_phone_types`	/PhoneTypes	Tipos de telefone
32	`get_products`	/Products	Produtos
33	`get_products_families`	/Products/Families	Famílias de produtos
34	`get_products_groups`	/Products/Groups	Grupos de produtos
35	`get_products_parts`	/Products/Parts	Partes de produtos
36	`get_quotes`	/Quotes	Propostas
37	`get_quotes_approval_status`	/Quotes/ApprovalStatus	Status de aprovação
38	`get_relative_dates`	/RelativeDates	Datas relativas
39	`get_roles`	/Roles	Cargos
40	`get_tags`	/Tags	Marcadores
41	`get_tasks`	/Tasks	Tarefas
42	`get_task_types`	/Tasks/Types	Tipos de tarefas
43	`get_task_repeat_interval_units`	/Tasks/RepeatIntervalUnits	Intervalos de repetição
44	`get_task_email_reminders`	/Tasks/EmailReminders	Lembretes de email
45	`get_teams`	/Teams	Equipes
46	`get_users`	/Users	Usuários
47	`get_user_profiles`	/Users/Profiles	Perfis de usuários
48	`get_webhooks`	/Webhooks	Webhooks
49	`get_webhook_actions`	/Webhooks/Actions	Ações de webhooks

Exemplos de Uso (via LLM)

"Liste os 10 primeiros contatos com nome e email"
→ get_contacts(top=10, select="Id,Name,Email")

"Quais são os negócios acima de R$ 50.000?"
→ get_deals(filter="Amount gt 50000")

"Mostre os funis de negócios com suas etapas"
→ get_deals_pipelines(expand="Stages")

Licença

MIT