MCP Clint CRM

Servidor MCP (Model Context Protocol) para integração com o Clint CRM. Gerencie contatos, negócios, tags, organizações e toda a configuração do seu CRM diretamente através de assistentes de IA compatíveis com MCP.

English version available here

Aviso: Este é um projeto open source mantido pela comunidade. Não é uma ferramenta oficial do Clint CRM. Utilize por sua conta e risco. Consulte a documentação oficial da API do Clint CRM para informações sobre a API.

Pré-requisitos

• Plano Elite do Clint CRM — O acesso à API requer o plano Elite ativo na sua conta Clint.

• API Key do Clint CRM — Chave de acesso gerada na sua conta Clint para autenticação na API.

• Python 3.14+ — O projeto utiliza recursos modernos do Python.

• UV — Gerenciador de pacotes e ambientes virtuais para Python. Instalar UV.

Links Úteis

• Documentação da API do Clint CRM

• Clint CRM

• Model Context Protocol (MCP)

Related MCP server: brasil-data-mcp

Instalação e Configuração

1. Clonar o repositório

git clone https://github.com/seu-usuario/mcp-clint-crm.git
cd mcp-clint-crm

2. Configurar as variáveis de ambiente

Crie um arquivo .env na raiz do projeto:

# Obrigatório — sua chave da API do Clint CRM
CLINT_API_KEY=sua_chave_api_aqui

# Opcional — necessário apenas para modo HTTP (ver seção "Deploy via HTTP")
CLINT_MCP_TRANSPORT=stdio
CLINT_MCP_HOST=0.0.0.0
CLINT_MCP_PORT=8001

# Opcional — Google OAuth (necessário para autenticação via Cowork/Claude.ai)
GOOGLE_CLIENT_ID=seu_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxx
GOOGLE_AUTH_BASE_URL=https://seu-servidor.com

# Opcional — Controle de acesso (requer Google OAuth ativo)
CLINT_MCP_RESTRICT_BY_EMAIL=false
CLINT_MCP_ALLOWED_EMAILS=usuario1@gmail.com,usuario2@gmail.com
CLINT_MCP_RESTRICT_BY_DOMAIN=false
CLINT_MCP_ALLOWED_DOMAINS=suaempresa.com

3. Instalar dependencias

uv sync

4. Executar o servidor (modo stdio)

uv run src/server.py

Configuracao via stdio (Claude Desktop, Cursor, etc.)

Para utilizar o servidor MCP com assistentes de IA que suportam o protocolo MCP via stdio, adicione a seguinte configuração no arquivo de configuração do seu cliente MCP.

Claude Desktop

No arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "clint-crm": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/caminho/absoluto/para/mcp-clint-crm",
        "src/server.py"
      ],
      "env": {
        "CLINT_API_KEY": "sua_chave_api_aqui"
      }
    }
  }
}

Cursor

No arquivo de configuração MCP do Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "clint-crm": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/caminho/absoluto/para/mcp-clint-crm",
        "src/server.py"
      ],
      "env": {
        "CLINT_API_KEY": "sua_chave_api_aqui"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add clint-crm -- uv run --directory /caminho/absoluto/para/mcp-clint-crm src/server.py

Nota: Substitua /caminho/absoluto/para/mcp-clint-crm pelo caminho real do projeto no seu sistema. A variável CLINT_API_KEY pode ser definida no .env do projeto ou diretamente na configuração env do cliente MCP.

Autenticação (Google OAuth)

O servidor suporta autenticação via Google OAuth, permitindo controlar quem pode acessar o MCP server via HTTP. A autenticação é opcional — se as variáveis GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET não estiverem definidas, o servidor aceita qualquer conexão.

Configurar o Google OAuth

1. Acesse o Google Cloud Console

2. Crie ou selecione um projeto

3. Vá em APIs & Services → Credentials → Create Credentials → OAuth Client ID

4. Tipo: Web application

5. Adicione a Redirect URI: https://seu-servidor.com/auth/callback

6. Copie o Client ID e Client Secret para o .env

Controle de acesso

Você pode restringir quem pode usar o servidor com duas opções (podem ser usadas juntas):

Por email — apenas emails específicos:

CLINT_MCP_RESTRICT_BY_EMAIL=true
CLINT_MCP_ALLOWED_EMAILS=frank@gmail.com,colega@empresa.com

Por domínio — qualquer email de um domínio:

CLINT_MCP_RESTRICT_BY_DOMAIN=true
CLINT_MCP_ALLOWED_DOMAINS=suaempresa.com,parceiro.com

Se ambos estiverem habilitados, o usuário precisa estar em pelo menos uma das listas para ter acesso.

Se nenhuma restrição estiver habilitada (false), qualquer conta Google autenticada terá acesso.

Deploy via HTTP (Servidor remoto / VPS / Cloud)

Para disponibilizar o MCP server via rede (ex: para uso com Claude.ai, Cowork, ChatGPT), o servidor roda em modo HTTP com transport Streamable HTTP.

Opção 1: Docker (recomendado)

git clone https://github.com/seu-usuario/mcp-clint-crm.git
cd mcp-clint-crm

Configure o .env:

CLINT_API_KEY=sua_chave_api_aqui

Suba o container:

docker compose up -d

O servidor estará disponível em http://seu-servidor:8001/mcp com health check automático em /health.

Opção 2: Uvicorn direto

cd mcp-clint-crm && uv sync
CLINT_MCP_TRANSPORT=streamable-http uv run uvicorn server:app --host 0.0.0.0 --port 8001 --app-dir src

Opção 3: VPS com PM2

cd mcp-clint-crm && uv sync
pm2 start "uv run uvicorn server:app --host 0.0.0.0 --port 8001 --app-dir src" --name clint-mcp

Configuração dos clientes MCP (HTTP)

Após o deploy, configure o cliente MCP com a URL do servidor.

Claude.ai / Cowork:

Adicione como custom connector na interface, ou no claude_desktop_config.json:

{
  "mcpServers": {
    "clint-crm": {
      "type": "http",
      "url": "https://seu-servidor.com/mcp"
    }
  }
}

ChatGPT / Codex:

{
  "mcpServers": {
    "clint-crm": {
      "url": "https://seu-servidor.com/mcp"
    }
  }
}

Importante: Em produção, use HTTPS (TLS) com um reverse proxy (Nginx, Caddy, etc.) na frente do servidor MCP. O servidor em si não faz terminação TLS.

Tools Disponíveis

O servidor expõe 27 tools organizadas por domínio. Cada tool é anotada com metadados de segurança (somente leitura / destrutiva) para que o assistente de IA solicite confirmação antes de executar ações perigosas.

Resumo

Contatos

list_contacts

Lista todos os contatos do CRM com filtros opcionais. Retorna até 1000 contatos por chamada com suporte a paginação.

get_contact

Retorna os detalhes completos de um contato pelo UUID.

create_contact

Cria um novo contato no CRM.

update_contact

Atualiza um contato existente. Envie apenas os campos que deseja alterar.

delete_contact

Remove permanentemente um contato. Ação destrutiva — requer confirmação.

add_tags

Adiciona uma ou mais tags a um contato.

remove_tags

Remove uma tag de um contato. Ação destrutiva — requer confirmação.

Negócios (Deals)

list_deals

Lista negócios com filtros avançados por data, status, usuário e tags. Retorna até 1000 negócios por chamada.

get_deal

Retorna os detalhes completos de um negócio pelo ID.

create_deal

Cria um novo negócio no CRM. Requer obrigatoriamente uma origem.

update_deal

Atualiza um negócio existente, incluindo mudanças de status e etapa do funil.

remove_deal

Remove permanentemente um negócio. Ação destrutiva — requer confirmação.

Tags

list_tags

Lista todas as tags com filtro opcional por nome.

get_tag

Retorna os detalhes de uma tag pelo ID.

create_tag

Cria uma nova tag com nome e cor.

Cores disponíveis:

delete_tag

Remove permanentemente uma tag. Ação destrutiva — requer confirmação.

Organizações

get_organization

Retorna os detalhes de uma organização pelo ID.

update_organization

Atualiza uma organização existente. Ação destrutiva — requer confirmação.

Origens

list_origins

Lista as origens filtradas por grupo. Cada origem contém suas etapas (stages) do funil.

get_origin

Retorna os detalhes de uma origem pelo ID.

Grupos

list_groups

Lista todos os grupos disponíveis no CRM.

get_group

Retorna os detalhes de um grupo pelo ID.

Usuários

list_users

Lista todos os usuários do sistema.

get_user

Retorna os detalhes de um usuário pelo ID.

Status de Perda

list_lost_status

Lista todos os motivos de perda de negócios.

get_lost_status

Retorna os detalhes de um status de perda pelo ID.

Conta

list_fields

Lista todos os campos personalizados configurados na conta. Use esta tool antes de criar ou atualizar contatos e negócios para descobrir os campos disponíveis e seus tipos.

Não requer parâmetros adicionais.

Campos Personalizados (Custom Fields)

Contatos, negócios e organizações suportam campos personalizados. O fluxo recomendado é:

1. Chame list_fields para descobrir os campos disponíveis, seus nomes-chave, tipos e opções.

2. Ao criar ou atualizar um registro, passe os campos no parâmetro fields como um objeto JSON:

{
  "campo_personalizado_1": "valor",
  "campo_personalizado_2": 123
}

Os campos podem ser passados como dict do Python ou como uma string JSON válida.

Paginação

Todas as operações de listagem retornam até 1000 registros por chamada. Para obter mais resultados, use o parâmetro offset:

• Primeira chamada: offset=0 (padrão)

• Segunda chamada: offset=1000

• Terceira chamada: offset=2000

• E assim por diante...

O servidor retorna o total de registros disponíveis e sugere o próximo offset quando há mais dados.

Stack Técnica

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues e pull requests. Se você está utilizando o projeto, favor considere marcar a estrela ⭐️.

Licença

Este projeto é open source. Consulte o arquivo de licença para mais detalhes.

Este projeto não é afiliado ao Clint CRM.