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)

---

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

Variável	Obrigatória	Descrição
CLINT_API_KEY	Sim	Chave da API do Clint CRM (plano Elite)
CLINT_MCP_TRANSPORT	Não	Transporte do servidor: stdio (padrão) ou streamable-http
CLINT_MCP_HOST	Não	Host do servidor HTTP (padrão: 0.0.0.0)
CLINT_MCP_PORT	Não	Porta do servidor HTTP (padrão: 8001)
GOOGLE_CLIENT_ID	Não	Client ID do Google OAuth (ver seção "Autenticação")
GOOGLE_CLIENT_SECRET	Não	Client Secret do Google OAuth
GOOGLE_AUTH_BASE_URL	Não	URL pública do servidor (padrão: http://localhost:8001)
CLINT_MCP_RESTRICT_BY_EMAIL	Não	true para restringir acesso por email (padrão: false)
CLINT_MCP_ALLOWED_EMAILS	Não	Emails permitidos (separados por vírgula)
CLINT_MCP_RESTRICT_BY_DOMAIN	Não	true para restringir acesso por domínio (padrão: false)
CLINT_MCP_ALLOWED_DOMAINS	Não	Domínios permitidos (separados por vírgula)

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

Domínio	Tools	Operações
Contatos	7	Listar, buscar, criar, atualizar, deletar, adicionar/remover tags
Negócios (Deals)	5	Listar, buscar, criar, atualizar, deletar
Tags	4	Listar, buscar, criar, deletar
Organizações	2	Buscar, atualizar
Origens	2	Listar, buscar
Grupos	2	Listar, buscar
Usuários	2	Listar, buscar
Status de Perda	2	Listar, buscar
Conta	1	Listar campos personalizados

---

Contatos

list_contacts

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

Parâmetro	Tipo	Descrição
offset	int	Deslocamento para paginação (padrão: 0)
name	str	Filtrar por nome do contato
phone	str	Filtrar por telefone (sem código do país)
email	str	Filtrar por e-mail
tag_names	str	Filtrar por tags (separadas por vírgula)
origin_id	str	Filtrar por origem (use list_origins para obter IDs)

get_contact

Retorna os detalhes completos de um contato pelo UUID.

Parâmetro	Tipo	Descrição
uuid	str	ID do contato (obtenha via list_contacts)

create_contact

Cria um novo contato no CRM.

Parâmetro	Tipo	Descrição
name	str	Nome do contato (obrigatório)
ddi	str	Código DDI do país
phone	str	Telefone
email	str	E-mail
username	str	Nome de usuário
fields	dict | str	Campos personalizados (JSON). Use list_fields para descobrir os campos disponíveis

update_contact

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

Parâmetro	Tipo	Descrição
uuid	str	ID do contato (obrigatório)
name	str	Novo nome
ddi	str	Novo DDI
phone	str	Novo telefone
email	str	Novo e-mail
username	str	Novo nome de usuário
fields	dict | str	Campos personalizados (JSON)

delete_contact

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

Parâmetro	Tipo	Descrição
uuid	str	ID do contato (obrigatório)

add_tags

Adiciona uma ou mais tags a um contato.

Parâmetro	Tipo	Descrição
uuid	str	ID do contato (obrigatório)
tag_names	list[str]	Lista de nomes de tags para adicionar

remove_tags

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

Parâmetro	Tipo	Descrição
uuid	str	ID do contato (obrigatório)
tag_name	str	Nome da tag para remover

---

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.

Parâmetro	Tipo	Descrição
offset	int	Deslocamento para paginação (padrão: 0)
created_at_start	str	Data inicial de criação (ISO 8601)
created_at_end	str	Data final de criação (ISO 8601)
updated_at_start	str	Data inicial de atualização (ISO 8601)
updated_at_end	str	Data final de atualização (ISO 8601)
user_email	str	Filtrar por e-mail do usuário responsável
phone	str	Filtrar por telefone
email	str	Filtrar por e-mail
tag_names	str	Filtrar por tags (separadas por vírgula)
status	str	Status: OPEN, WON ou LOST (padrão: OPEN)
won_at_start	str	Data inicial de ganho (ISO 8601)
won_at_end	str	Data final de ganho (ISO 8601)
lost_at_start	str	Data inicial de perda (ISO 8601)
lost_at_end	str	Data final de perda (ISO 8601)
stage_id	str	Filtrar por etapa do funil

get_deal

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

Parâmetro	Tipo	Descrição
id	str	ID do negócio (obtenha via list_deals)

create_deal

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

Parâmetro	Tipo	Descrição
origin_id	str	ID da origem (obrigatório, use list_origins)
name	str	Nome do contato
phone	str	Telefone
email	str	E-mail
username	str	Nome de usuário
value	float	Valor do negócio
stage_id	str	ID da etapa do funil
user_id	str	ID do usuário responsável
contact_id	str	ID do contato existente
fields	dict | str	Campos personalizados (JSON)

update_deal

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

Parâmetro	Tipo	Descrição
id	str	ID do negócio (obrigatório)
name	str	Novo nome
phone	str	Novo telefone
email	str	Novo e-mail
value	float	Novo valor
stage_id	str	Nova etapa do funil
status	str	Novo status: OPEN, WON ou LOST
user_id	str	Novo usuário responsável
origin_id	str	Nova origem
fields	dict | str	Campos personalizados (JSON)

remove_deal

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

Parâmetro	Tipo	Descrição
id	str	ID do negócio (obrigatório)

---

Tags

list_tags

Lista todas as tags com filtro opcional por nome.

Parâmetro	Tipo	Descrição
offset	int	Deslocamento para paginação (padrão: 0)
name	str	Filtrar por nome da tag

get_tag

Retorna os detalhes de uma tag pelo ID.

Parâmetro	Tipo	Descrição
id	str	ID da tag (obtenha via list_tags)

create_tag

Cria uma nova tag com nome e cor.

Parâmetro	Tipo	Descrição
name	str	Nome da tag (obrigatório)
color	str	Cor em hexadecimal (padrão: #f44336)

Cores disponíveis:

Cor	Código
Vermelho	#f44336
Rosa	#e91e63
Roxo	#9c27b0
Roxo escuro	#673ab7
Azul	#2196f3
Laranja	#faa200
Marrom	#795548
Cinza azulado	#607d8b

delete_tag

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

Parâmetro	Tipo	Descrição
id	str	ID da tag (obrigatório)

---

Organizações

get_organization

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

Parâmetro	Tipo	Descrição
id	str	ID da organização

update_organization

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

Parâmetro	Tipo	Descrição
id	str	ID da organização (obrigatório)
name	str	Novo nome
custom_fields	dict | str	Campos personalizados (JSON)

---

Origens

list_origins

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

Parâmetro	Tipo	Descrição
group_id	str	ID do grupo (obrigatório, use list_groups)
offset	int	Deslocamento para paginação (padrão: 0)

get_origin

Retorna os detalhes de uma origem pelo ID.

Parâmetro	Tipo	Descrição
id	str	ID da origem (obtenha via list_origins)

---

Grupos

list_groups

Lista todos os grupos disponíveis no CRM.

Parâmetro	Tipo	Descrição
offset	int	Deslocamento para paginação (padrão: 0)

get_group

Retorna os detalhes de um grupo pelo ID.

Parâmetro	Tipo	Descrição
id	str	ID do grupo (obtenha via list_groups)

---

Usuários

list_users

Lista todos os usuários do sistema.

Parâmetro	Tipo	Descrição
offset	int	Deslocamento para paginação (padrão: 0)

get_user

Retorna os detalhes de um usuário pelo ID.

Parâmetro	Tipo	Descrição
id	str	ID do usuário (obtenha via list_users)

---

Status de Perda

list_lost_status

Lista todos os motivos de perda de negócios.

Parâmetro	Tipo	Descrição
offset	int	Deslocamento para paginação (padrão: 0)

get_lost_status

Retorna os detalhes de um status de perda pelo ID.

Parâmetro	Tipo	Descrição
id	str	ID do status (obtenha via list_lost_status)

---

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

Tecnologia	Versão	Propósito
Python	3.14+	Linguagem principal
FastMCP	3.1.1+	Framework MCP
httpx	0.28.1+	Cliente HTTP assíncrono
Pydantic	2.12.5+	Validação de dados e modelos
UV	-	Gerenciador de pacotes
Docker	-	Containerização (opcional)

---

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.}