# Ploomes MCP Server — Read-Only

Servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) que expõe **somente operações de leitura (GET)** da API do CRM [Ploomes](https://www.ploomes.com/).

> ⚠️ 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

```bash
# 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:

```env
# 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.)

```bash
python -m src.server
```

### Modo HTTP

```bash
set MCP_TRANSPORT=http
python -m src.server
```

### MCP Inspector (para desenvolvimento)

```bash
mcp dev src/server.py
```

## Documentação Completa

- 🛠️ **[Guia de Configuração e Uso (docs/setup_guide.md)](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)](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`:

```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`:

```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`):

```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