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