Attio MCP Server

Servidor MCP Attio

Um servidor abrangente de Model Context Protocol (MCP) para Attio, fornecendo cobertura completa da superfície do CRM. Este servidor permite que assistentes de IA como Claude e ChatGPT interajam diretamente com todo o seu workspace Attio por meio de linguagem natural—gerencie Negócios, Tarefas, Listas, Pessoas, Empresas, Registros e Notas sem depender de chamadas brutas de API.

🎯 O que é o Servidor MCP Attio?

Transforme seus fluxos de trabalho de CRM com automação impulsionada por IA. Em vez de clicar em várias telas, basta pedir ao Claude ou ao ChatGPT para encontrar prospects, atualizar registros, gerenciar pipelines e analisar seus dados usando comandos em linguagem natural.

🎉 Marco v1.0.0: Cobertura completa da superfície do CRM Attio com integração total ao Modo Desenvolvedor do ChatGPT.

"Encontre todas as empresas de IA com mais de 50 funcionários que não contatamos há 30 dias e adicione-as à nossa lista de divulgação do Q1"

🚀 Integração com o Modo Desenvolvedor do ChatGPT

⚠️ Smithery Temporariamente Indisponível: A Smithery mudou seu modelo de implantação para exigir hospedagem externa. Estamos trabalhando na hospedagem via Cloudflare Worker para usuários do ChatGPT. Enquanto isso, use o Nível 4 (Cloudflare Worker) para acesso remoto/ChatGPT.

Usuários do ChatGPT Pro/Plus podem acessar o conjunto de ferramentas do Attio por meio de linguagem natural usando um Cloudflare Worker auto-hospedado:

• 🔐 Fluxos de Aprovação Integrados: Anotações de segurança do MCP aprovam automaticamente operações de leitura e solicitam aprovação para gravações
• 🌐 Integração OAuth: OAuth auto-hospedado via implantação do Cloudflare Worker
• 💬 CRM em Linguagem Natural: Gerencie todo o seu workspace Attio por meio de IA conversacional
• 📖 Guia de Configuração: Consulte a documentação do Modo Desenvolvedor do ChatGPT e o Guia do Cloudflare Worker

✨ Recursos Principais e Status de Implementação

🎯 Arquitetura de Ferramentas Universais (19 Operações Universais)

Superfície de Ferramentas Focada: Consolidamos mais de 40 ferramentas específicas por recurso em operações universais e, em seguida, adicionamos ferramentas de gravação de alta frequência com escopo definido para atualizações mais seguras de empresas e negócios.

• Alto Desempenho: Melhoria de 89,7% na velocidade com redução de 227KB de memória (PR #483)
• Qualidade Empresarial: Pontuação de prontidão para produção de 97,15/100 com zero mudanças que quebram o sistema
• Arquitetura Limpa: Separação completa entre produção e testes com padrão de fábrica de mocks
• Política de Ferramentas com Escopo: Adicione ferramentas padrão com escopo somente quando o fluxo de trabalho for frequente, uma gravação genérica puder alterar a classe errada de objeto e a ferramenta com escopo eliminar uma decisão de modelo em vez de apenas renomear uma chamada universal

📊 Status de Implementação de Recursos

✅ Cobertura Completa da Superfície do CRM

• Empresas: Pesquisa, Criação, Atualização, Exclusão, Pesquisa Avançada, Pesquisa de Relacionamento
• Pessoas: Pesquisa, Criação, Atualização, Exclusão, Pesquisa Avançada, Pesquisa de Relacionamento
• Negócios: Operações completas de CRUD com mapeamento inteligente de campos e validação de etapas
• Tarefas: Criação, Atualização, Exclusão, Pesquisa com suporte a múltiplos responsáveis
• Listas: Operações completas de CRUD, filtragem, filtragem avançada, gerenciamento de entradas
• Notas: Operações de criação e listagem para todos os tipos de registro
• Registros: Operações universais de CRUD em todos os tipos de recurso
• Operações em Lote: Criação, Atualização, Exclusão com divisão em blocos e tratamento de erros
• Pesquisa de Conteúdo: Capacidades universais de pesquisa em notas, tarefas e listas
• Navegação de Relacionamento: Relacionamentos bidirecionais empresa↔pessoa↔negócio
• Filtragem Avançada: Capacidades sofisticadas de consulta com mapeamento inteligente de campos

📊 Gerenciamento de Empresas

• Pesquisa Universal: Encontre empresas com search_records e search_records_advanced
• Gravações com Escopo: Crie e atualize empresas com create_company e update_company
• CRUD Completo: Crie, leia, atualize e exclua com operações universais de registro quando uma ferramenta com escopo não estiver disponível
• Descoberta de Relacionamentos: Encontre empresas por meio de search_records_by_relationship
• Operações em Lote: Processe centenas de empresas com batch_records
• Informações Detalhadas: Obtenha informações de contato, comerciais e sociais com get_record_info

👥 Gerenciamento de Pessoas

• Pesquisa Universal de Contatos: Encontre pessoas por qualquer critério usando ferramentas universais de pesquisa
• Rastreamento de Relacionamentos: Vincule pessoas a empresas com search_records_by_relationship
• Linha do Tempo de Atividades: Acompanhe interações com search_records_by_content e search_records_by_timeframe
• Filtragem Avançada: Pesquisa multi-atributo com filtragem universal
• Operações em Massa: Gerencie contatos com eficiência usando operações universais em lote

📋 Gerenciamento de Listas e Pipeline (6 Ferramentas + 8 Obsoletas)

• Ferramentas Ativas: 4 ferramentas consolidadas com detecção automática de modo (Guia de Migração)
  • filter-list-entries - Filtragem unificada com 4 modos
  • manage-list-entry - Gerenciamento unificado de entradas com 3 modos
  • get-list-entries - Recuperar entradas de lista
  • get-record-list-memberships - Encontrar associações de lista de um registro
• Ferramentas de Configuração de Listas (dedicadas; create_record/update_record universais rejeitam resource_type: "lists"):
  • create-list - Crie listas com controles de acesso de primeira classe: workspace_access (full-access | read-and-write | read-only | "null" para uma lista privada) e workspace_member_access (concessões por membro). Omitir ambos os campos de acesso define a nova lista como acesso total em todo o workspace; novas listas devem manter pelo menos um beneficiário com acesso total.
  • update-list-configuration - Atualize nome, campos personalizados e os mesmos controles de acesso. Concessões em nível de membro podem elevar o acesso acima do padrão do workspace, mas nunca reduzi-lo abaixo de workspace_access.
  • Erros distinguem plan_gating (o plano do workspace não suporta a configuração de acesso solicitada) de permission_failure (permissões de token/workspace) e unsupported_input (configuração de acesso malformada), cada um com uma próxima etapa sugerida.
• Obsoletas (remoção na v2.0.0): 8 ferramentas legadas substituídas por versões consolidadas
• Operações de Pipeline: Mova negócios pelas etapas de vendas
• Segmentação Inteligente: Crie e gerencie listas de contatos direcionadas
• Filtragem Avançada: Filtragem complexa com múltiplas condições usando lógica AND/OR
• Gerenciamento de Entradas: Adicione, remova e atualize associações de lista
• Rastreamento de Negócios: Monitore oportunidades e pipeline de receita
• Padrões de Negócios: Etapa, proprietário e moeda padrão configuráveis para criação simplificada de negócios
• Gravações de Negócios com Escopo: Crie e atualize negócios com create_deal e update_deal

✅ Gerenciamento de Tarefas

• Operações Universais de Tarefas: Crie, atualize e gerencie tarefas com ferramentas universais
• Vinculação de Registros: Associe tarefas a qualquer tipo de registro usando o parâmetro resource_type
• Rastreamento de Progresso: Monitore a conclusão com pesquisa e filtragem universais
• Coordenação de Equipe: Simplifique acompanhamentos com operações universais consistentes

🔧 Capacidades Avançadas

• Processamento em Lote: Lide com operações em massa com rastreamento de erros
• Filtragem Aprimorada: Filtros de texto, numéricos, de data, booleanos e de relacionamento com pesquisa por período (Issue #475)
• Exportação de Dados: Serialização JSON para integrações
• Atualizações em Tempo Real: Sincronização de dados ao vivo com Attio

🧠 Habilidades do Claude

Potencialize o conhecimento do Claude sobre Attio com habilidades pré-construídas que previnem erros comuns e ensinam melhores práticas.

Início Rápido (resolve erros de "nome de campo incorreto"):

npx attio-discover generate-skill --all --zip
# Import ZIP into Claude Desktop: Settings > Skills > Install Skill

Consulte a Documentação de Habilidades para guias completos de configuração e uso.

💬 Prompts Pré-Construídos (10 Prompts)

Atalhos inteligentes que ajudam o Claude a trabalhar mais rápido com seus dados de CRM:

• Pesquisar e Encontrar (5): people_search, company_search, deal_search, meeting_prep, pipeline_health
• Executar Ações (4): log_activity, create_task, advance_deal, add_to_list com segurança de simulação (dry-run)
• Pesquisar e Qualificar (1): qualify_lead com pesquisa web automatizada e estruturas BANT/CHAMP
• Eficiente em Tokens: 300-700 tokens por prompt com formatação consistente
• Detectável: O Claude sugere automaticamente prompts relevantes para suas tarefas

Consulte Como Usar Prompts Prontos para documentação detalhada e exemplos.

🎯 Como Usar Prompts Prontos

NOVO: 10 prompts MCP pré-construídos para fluxos de trabalho comuns de Vendas. Sem configuração necessária—basta usá-los!

Prompts Disponíveis

Exemplos Rápidos

# Search for prospects
"Use people_search.v1: Find Account Executives in San Francisco at fintech companies, limit 25"

# Log activity
"Use log_activity.v1: Log a call with Nina at Acme Corp, discussed Q1 pricing, create follow-up task"

# Qualify a lead (with web research)
"Use qualify_lead.v1: Qualify Acme Corp using BANT framework, dry run mode"

# Meeting prep
"Use meeting_prep.v1: Prepare for meeting with contact at Acme Corp"

Argumentos Universais

Todos os prompts de leitura suportam:

• format: table | json | ids (padrão: table)
• fields_preset: sales_short | full (padrão: sales_short)
• verbosity: brief | normal (padrão: brief)

Todos os prompts de gravação suportam:

• dry_run: true | false (padrão: false) - Visualize alterações sem executar

Recursos de Conscientização de Tokens

Os prompts incluem otimização integrada de tokens:

• Proteções de Orçamento: Prompts permanecem dentro dos limites de tokens (people_search <500, qualify_lead <400)
• Metadados de Desenvolvimento: Defina MCP_DEV_META=true para contagens de tokens nas respostas
• Telemetria: Defina PROMPT_TELEMETRY_ENABLED=true para registro de uso
• Limites Configuráveis: Substitua com a variável de ambiente MAX_PROMPT_TOKENS

Para documentação completa de prompts, consulte docs/prompts/v1-catalog.md.

⚠️ Limitações Conhecidas e Notas Importantes

Limitações Atuais

• Filtragem de Parâmetros de Campo: O endpoint de tarefas /objects/tasks/attributes tem limitações, tratadas com padrões de fallback
• Paginação: A paginação de tarefas usa manipulação em memória devido a restrições da API

Compatibilidade da API

• Ferramentas Universais: Interface primária (19 ferramentas) - recomendada para todas as novas integrações
• Ferramentas Legadas: Disponíveis via variável de ambiente DISABLE_UNIVERSAL_TOOLS=true (obsoletas)
• API de Listas: Totalmente funcional com operações CRUD completas (contrariando alguma documentação desatualizada)

🤝 Compatibilidade com OpenAI MCP

• Pronto para Modo Desenvolvedor: Cada ferramenta agora publica anotações de segurança MCP (readOnlyHint, destructiveHint) para que o Modo Desenvolvedor da OpenAI possa aprovar automaticamente leituras e solicitar confirmação para gravações.
• Acesso Total às Ferramentas (Padrão): Todas as 41 ferramentas são expostas por padrão (26 universais/OpenAI + 12 de lista + 3 membros do workspace). NÃO defina ATTIO_MCP_TOOL_MODE na configuração do Smithery para acesso total.
• Modo Somente Pesquisa: Para restringir a ferramentas somente leitura (search, fetch, aaa-health-check), configure explicitamente ATTIO_MCP_TOOL_MODE: 'search' no painel do Smithery quando o Modo Desenvolvedor não estiver disponível.
• Guia Detalhado: Consulte docs/chatgpt-developer-mode.md para variáveis de ambiente, fluxos de aprovação e dicas de validação.
• Documentação do Usuário: Consulte a documentação do Modo Desenvolvedor do ChatGPT para um passo a passo completo dos fluxos de aprovação e instruções de configuração.

Considerações de Desempenho

• Operações em Lote: Otimizadas com agrupamento, limitação de taxa e recuperação de erros
• Grandes Conjuntos de Dados: Paginação automática e filtragem de campos para desempenho ideal
• Limitação de Taxa: Proteção integrada contra limites de taxa da API com backoff exponencial

Para solução de problemas detalhada e soluções, consulte TROUBLESHOOTING.md e Problemas no GitHub.

🎯 Filtros de Pesquisa Avançados

Crie consultas CRM poderosas com filtragem AND/OR de múltiplos critérios. Consulte o Guia de Pesquisa Avançada para exemplos completos e referência de operadores.

🚀 Instalação

⚠️ IMPORTANTE: Nome Correto do Pacote

O nome do pacote npm é attio-mcp (não attio-mcp-server). O repositório GitHub é nomeado attio-mcp-server, mas o pacote npm foi renomeado para attio-mcp em junho de 2025. Instalar attio-mcp-server fornecerá uma versão desatualizada v0.0.2 com apenas 4 ferramentas legadas.

Compatibilidade com Clientes

Escolha seu método de instalação:

• Maioria dos usuários: Use Nível 1 (Instaladores Shell) - um comando, configuração automática
• Usuários avançados: Use Nível 2 (Manual) - controle total sobre a configuração
• ChatGPT/Teams/Enterprise: Use Nível 3 (Cloudflare Worker) - auto-hospedado, OAuth multiusuário

Nível 1: Instaladores Shell

Melhor para: Desenvolvedores que preferem instalações locais com configuração automática.

Scripts de um comando que instalam attio-mcp e configuram seu cliente automaticamente.

Claude Desktop

curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/scripts/install-claude-desktop.sh | bash

Cursor IDE

curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/scripts/install-cursor.sh | bash

Claude Code (CLI)

curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/scripts/install-claude-code.sh | bash

Esses scripts irão:

• Instalar o pacote npm attio-mcp globalmente (se necessário)
• Fazer backup dos arquivos de configuração existentes
• Solicitar sua chave de API Attio
• Configurar o servidor MCP para seu cliente
• Imprimir próximos passos e instruções de reinicialização

Nível 2: Configuração Manual

Melhor para: Usuários avançados que preferem controle total ou usam clientes não suportados.

npm install -g attio-mcp

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here"
      }
    }
  }
}

npm install -g attio-mcp

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here"
      }
    }
  }
}

echo '{"command":"attio-mcp","env":{"ATTIO_API_KEY":"your_key_here"}}' | claude mcp add-json attio-mcp --stdin -s user

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here"
      }
    }
  }
}

git clone https://github.com/kesslerio/attio-mcp-server.git
cd attio-mcp-server
npm install
npm run build

ATTIO_API_KEY=your_key node dist/index.js

# Global installation for CLI usage
npm install -g attio-mcp

# Or local installation for project integration
npm install attio-mcp

Nível 3: Cloudflare Worker (Implantação Remota)

Melhor para: Equipes que precisam de OAuth centralizado, acesso multiusuário, acesso móvel ou execução de MCP sem instalação local.

Implante seu próprio servidor MCP Attio no Cloudflare Workers com suporte completo a OAuth 2.1.

Acesso Móvel: Com um servidor MCP remoto, você pode usar ferramentas Attio de:

• Aplicativo móvel ChatGPT (iOS/Android)
• Aplicativo móvel Claude (iOS/Android)
• Qualquer navegador em qualquer dispositivo

Recursos do Cloudflare Worker

Implantação Rápida

cd examples/cloudflare-mcp-server
npm install
wrangler kv:namespace create "TOKEN_STORE"
# Update wrangler.toml with the KV namespace ID
wrangler secret put ATTIO_CLIENT_ID
wrangler secret put ATTIO_CLIENT_SECRET
wrangler secret put TOKEN_ENCRYPTION_KEY
wrangler deploy

Configuração do Cliente

Após a implantação, configure seu cliente com a URL do seu Worker:

• Claude.ai: Configurações → Conectores → Adicione a URL do seu Worker
• ChatGPT: Configurações → Conectores → Modo Desenvolvedor → Adicione a URL do Worker

Consulte o Guia de Implantação do Cloudflare Worker para:

• Configuração completa de OAuth 2.1 com Attio
• Configuração de criptografia de tokens
• Lista de verificação de implantação em produção
• Guia de solução de problemas

🆕 Novidades na v1.4.0

Principais Recursos

• 🎯 Gerador de Skill de Esquema do Workspace (#983) - Gere automaticamente Skills do Claude a partir do esquema do seu workspace Attio para nomes de campos e opções sem erros
• 🔍 Transformador de Campos de Seleção (#1019) - Correspondência sem diferenciar maiúsculas/minúsculas, correspondência parcial e passagem de UUID para campos de seleção/status
• 🛠️ Meta-skill Geradora de Skills Attio (#1020) - Meta-skill para documentação automática do workspace
• 📚 Skill de Guia de Uso Universal (#1018) - Padrões de fluxo de trabalho artesanais e prevenção de erros
• ⚙️ Ferramenta get_record_attribute_options (#975) - Obtenha opções válidas para campos de seleção/status com mensagens de erro aprimoradas
• 📞 Validação de telefone (#951) - Suporte integrado à validação de números de telefone
• ⏱️ Atraso configurável na busca de opções - Controle de limitação de taxa via sinalizador --option-fetch-delay

Principais Aprimoramentos

• 🏷️ Nomenclatura de ferramentas compatível com MCP (#1039) - Todas as ferramentas agora usam snake_case, nomenclatura verbo-primeiro (nomes antigos funcionam via aliases até v2.0.0)
• 🎨 Nomes de exibição personalizados de objetos (#1017) - Busque nomes de exibição diretamente da API Attio
• 📖 Padrões de integração divididos (#1023) - Padrões de descoberta progressiva por caso de uso
• 💡 Mensagens de erro de atributos aprimoradas (#975) - Sugestões de distância de Levenshtein para erros de digitação

Correções Críticas

• 📝 Quebras de linha preservadas no conteúdo de notas (#1052)
• 👤 Exibição "Sem nome" na pesquisa de pessoas corrigida (#1051)
• ✅ Persistência de campos de seleção (#1045)
• 🔗 Transformação automática de referência de registro (#997)
• 📊 Transformação automática de array multisseleção (#992)
• 🛡️ Validação de atributos complexos (#991)
• ⚠️ Avisos falsos de persistência de campos (#995)
• 📦 Fixação de dependências do SDK (#1025)
• 💼 Validação de estágio/UTM de negócios (#1043)
• 📍 Normalização automática de campos de localização (#987)

Melhorias Internas

• Refatoração do sistema de aliases de ferramentas (#1041) - Constantes type-safe com geração baseada em padrões
• Padrão de Estratégia para manipuladores de erros CRUD (#1001)
• Busca de metadados consolidada (#984)
• Modularização do UniversalUpdateService (#984)
• Renomeação do tipo de transformação de seleção (#1055) - select_title_to_array para clareza

🔄 Guia de Migração

Atualizando da v1.3.x ou anterior? Os nomes das ferramentas mudaram para seguir as convenções de nomenclatura MCP.

Nomes antigos ainda funcionam via aliases compatíveis com versões anteriores, mas serão removidos na v2.0.0 (Q1 2026).

Alterações de Nomes de Ferramentas

Ação Necessária: Atualize suas integrações para usar os novos nomes de ferramentas antes do Q1 2026. Consulte MIGRATION-GUIDE.md para a tabela de migração completa.

⚡ Início Rápido

Pré-requisitos

• Node.js (v18 ou superior)
• Chave de API Attio (Obtenha uma aqui) ou token de acesso OAuth
• ID do Workspace Attio

🔐 Opções de Autenticação

O servidor suporta dois métodos de autenticação—ambos usam o mesmo esquema de token Bearer:

Nota: Se ambos estiverem definidos, ATTIO_API_KEY tem precedência.

Usuários OAuth: Para configuração detalhada incluindo fluxo PKCE e renovação de token, consulte Guia de Autenticação OAuth.

1. Definir Variáveis de Ambiente

# Option 1: API Key (recommended for most users)
export ATTIO_API_KEY="your_api_key_here"

# Option 2: OAuth Access Token (for OAuth integrations)
# export ATTIO_ACCESS_TOKEN="your_oauth_access_token_here"

export ATTIO_WORKSPACE_ID="your_workspace_id_here"

# Optional: Deal defaults configuration
export ATTIO_DEFAULT_DEAL_STAGE="Interested"           # Default stage for new deals
export ATTIO_DEFAULT_DEAL_OWNER="user@company.com"     # Default owner email address (see below)
export ATTIO_DEFAULT_CURRENCY="USD"                    # Default currency for deal values

2. Testar a Instalação

# Test the MCP server
attio-mcp --help

# Discover your Attio workspace attributes
attio-discover attributes

3. 🎯 CRÍTICO: Configurar Mapeamentos de Campos

O servidor MCP usa arquivos de mapeamento de campos para traduzir entre linguagem natural e os nomes de campos da API do Attio. Esta configuração é essencial para o funcionamento adequado.

Configuração Rápida

# 1. Copy the sample configuration to create your user config
cp configs/runtime/mappings/sample.json configs/runtime/mappings/user.json

# 2. Edit user.json to match your workspace's custom fields
# Focus on the "objects.companies" and "objects.people" sections

Arquivos de Configuração (em configs/runtime/mappings/)

• default.json - Campos padrão do CRM Attio (carregado primeiro, não edite)
• sample.json - Exemplos com modelos de campos personalizados (copie deste, não usado em tempo de execução)
• user.json - Substituições específicas do SEU workspace (mesclado sobre default.json)

💡 Insight Principal: user.json é mesclado sobre default.json, então inclua apenas substituições e adições. Não duplique mapeamentos que já existem em default.json.

Como Funciona a Mesclagem de Configuração

O servidor MCP carrega a configuração nesta ordem:

1. default.json - Contém todos os campos padrão do Attio (Nome, Descrição, Equipe, etc.)
2. user.json - Suas adições/substituições personalizadas são mescladas por cima

Exemplo: Se default.json tem "Name": "name" e seu user.json também tem "Name": "name", isso é desperdício de tokens. Inclua apenas campos que sejam:

• Novos campos personalizados (não presentes em default.json)
• Mapeamentos diferentes (substituindo o comportamento padrão)

Exemplo Otimizado de user.json

{
  "mappings": {
    "attributes": {
      "objects": {
        "companies": {
          "// Only your custom fields - defaults are inherited": "",
          "Lead Score": "lead_score",
          "B2B Segment": "b2b_segment",
          "Industry Vertical": "custom_industry_field"
        }
      }
    },
    "lists": {
      "// Only your specific lists": "",
      "Sales Pipeline": "your-pipeline-list-id"
    }
  }
}

✅ Bom: Apenas campos personalizados/substituições
❌ Desperdício: Duplicar campos padrão de default.json

⚠️ Sem a configuração adequada de mapeamento, o servidor MCP pode não funcionar corretamente com seus campos e listas personalizados.

Próximo: Verifique se seus mapeamentos de campos funcionam testando com Claude:

"Find companies in our pipeline with lead score > 80"

4. Configurar o Claude Desktop

Adicione à sua configuração MCP do Claude Desktop:

Encontrando IDs Necessários

E-mail do Proprietário do Negócio (para padrões de proprietário de negócio): O ATTIO_DEFAULT_DEAL_OWNER deve ser definido para o endereço de e-mail do membro do workspace que deve ser o proprietário padrão de novos negócios. Normalmente, este é o seu próprio endereço de e-mail ou o endereço de e-mail do líder da sua equipe de vendas.

# Example:
export ATTIO_DEFAULT_DEAL_OWNER="john.smith@company.com"

Nota: O sistema resolverá automaticamente endereços de e-mail para referências de membros do workspace ao criar negócios.

Etapas do Negócio: As etapas do negócio são específicas do seu workspace. Verifique as configurações do seu workspace no Attio ou use o comando discover-attributes para encontrar as etapas disponíveis para negócios.

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here",
        "ATTIO_WORKSPACE_ID": "your_workspace_id_here",
        "ATTIO_DEFAULT_DEAL_STAGE": "Interested",
        "ATTIO_DEFAULT_DEAL_OWNER": "user@company.com",
        "ATTIO_DEFAULT_CURRENCY": "USD"
      }
    }
  }
}

🌟 Exemplos de Casos de Uso

Para Equipes de Vendas

"Find all companies in the AI space with 50+ employees that we haven't contacted in 30 days"
"Show me all prospects added yesterday"
"Find companies created in the last 7 days with revenue over $10M"
"Create a task to follow up with Microsoft about the enterprise deal"
"Add John Smith from Google to our Q1 prospect list"

Para Equipes de Marketing

"Create a list of all SaaS companies who opened our last 3 emails but haven't responded"
"Show me engagement metrics for our outbound campaign this month"
"Add all attendees from the conference to our nurture sequence"

Para Sucesso do Cliente

"Show me all enterprise customers with upcoming renewal dates in Q1"
"Create tasks for check-ins with accounts that haven't been contacted in 60 days"
"Find all customers who mentioned pricing concerns in recent notes"

Para Operações de Dados

"Update all companies with missing industry data based on their domains"
"Export all contacts added this quarter to CSV"
"Merge duplicate company records for Acme Corporation"

🔐 Segurança e Privacidade

• Autenticação Segura de API: Autenticação padrão da indústria com chave de API
• Sem Armazenamento de Dados: Passagem direta de API sem retenção local de dados
• Código Aberto: Transparência total com licença Apache 2.0
• On-Premises Opcional: Implante em sua própria infraestrutura
• Proveniência npm: Publicado com proveniência Sigstore — cada versão é criptograficamente vinculada ao build do GitHub Actions e ao commit de origem

Verificação da Cadeia de Suprimentos

Este pacote é publicado com proveniência npm, criando uma cadeia verificável do código-fonte ao artefato publicado. Verifique uma versão:

# Check provenance attestation on any published version
npm view attio-mcp --json | jq .attestations

# With pnpm (v10+), enforce trust policy at install time
# pnpm trustPolicy: no-downgrade blocks packages published with weaker credentials

Para máxima proteção da cadeia de suprimentos, instale com pnpm v10+ que impõe:

• trustPolicy: no-downgrade — bloqueia versões publicadas com credenciais mais fracas que versões anteriores
• minimumReleaseAge — período de espera antes que novas versões possam ser instaladas

📚 Documentação

Documentação abrangente está disponível no diretório docs:

Ferramentas Universais (Recomendado)

⚠️ Nota: A documentação de ferramentas universais está sendo atualizada para corresponder à implementação mais recente. Use a API diretamente ou consulte o código-fonte para as definições de interface mais precisas.

• Visão Geral da API - Conceitos e padrões de API de alto nível
• Código-Fonte das Ferramentas Universais - Referência de implementação atual
• Esquemas de Ferramentas - Definições de parâmetros e validação

Primeiros Passos

• Instalação e Configuração
• Configuração do Claude Desktop
• Guia de Solução de Problemas

Configuração

• Configuração de Filtro de Avisos - Entendendo incompatibilidades cosméticas vs. semânticas, orçamentos ESLint e estratégias de supressão
• Configuração de Verificação de Campos - Verificação de persistência de campos e configurações de validação
• Configuração de Pontuação de Busca - Variáveis de ambiente para pontuação de relevância, cache e validação de operadores

Referência da API

📋 Status de Implementação: Estes documentos descrevem os endpoints da API do Attio. Para uso de ferramentas MCP, consulte a documentação de ferramentas universais acima.

• Visão Geral da API - Conceitos gerais da API do Attio
• API de Empresas - Endpoints de registros de empresas ✅ Totalmente Implementado via Ferramentas Universais
• API de Pessoas - Endpoints de registros de pessoas ✅ Totalmente Implementado via Ferramentas Universais
• API de Listas - Endpoints de gerenciamento de listas ✅ Totalmente Implementado
• API de Notas - Endpoints de notas ✅ Implementação Básica
• API de Tarefas - Endpoints de tarefas ✅ Implementado via Ferramentas Universais

Tópicos Avançados

• Operações em Lote - Operações em massa ✅ Implementado com divisão em blocos
• Filtragem Avançada - Consultas complexas ✅ Implementado
• Tratamento de Erros - Padrões de erros ✅ Tratamento de erros aprimorado
• Estendendo o MCP - Guia de personalização

Implantação

• Guia Docker
• Melhores Práticas de Segurança

🛠 Desenvolvimento

Configurar Ambiente de Desenvolvimento

git clone https://github.com/kesslerio/attio-mcp-server.git
cd attio-mcp-server
npm install
npm run build
npm run test:offline

Desenvolvimento com Smithery CLI

Para desenvolvimento local e testes com o Smithery Playground:

npm run dev  # Opens Smithery Playground with local server

Consulte docs/deployment/smithery-cli-setup.md para configuração detalhada de desenvolvimento com Smithery CLI.

Testes

npm test                    # Run all tests
npm run test:offline        # Run only offline tests (no API required)
npm run test:integration    # Integration tests (requires ATTIO_API_KEY)
npm run e2e                 # E2E tests (requires ATTIO_API_KEY)

Para testes E2E/integração, crie .env com seu ATTIO_API_KEY. Consulte o Guia de Testes para configuração detalhada.

Scripts Disponíveis

npm run build          # Build TypeScript
npm run test           # Run all tests
npm run test:offline   # Run tests without API calls
npm run analyze:token-footprint # Generate baseline MCP token footprint report
npm run lint           # Check code style
npm run check          # Full quality check
npm run setup:test-data # Create test data for integration tests

🤝 Contribuindo

Aceitamos contribuições! Consulte nossas Diretrizes de Contribuição para detalhes sobre:

• Adicionar novas ferramentas e recursos
• Melhorar a documentação
• Relatar bugs e solicitar recursos
• Testes e garantia de qualidade

📈 O Que Vem a Seguir?

Esta versão inicial fornece uma base sólida para automação de CRM.

🔗 Links

• Pacote NPM: https://www.npmjs.com/package/attio-mcp
• Repositório GitHub: https://github.com/kesslerio/attio-mcp-server
• Issues e Suporte: https://github.com/kesslerio/attio-mcp-server/issues
• Versões: https://github.com/kesslerio/attio-mcp-server/releases
• Documentação do Attio: https://developers.attio.com/

📄 Licença

Este projeto é licenciado sob a Apache License 2.0 - consulte o arquivo LICENSE para detalhes.

Atribuição do Trabalho Original: Este projeto é baseado no trabalho inicial de @hmk sob licença BSD-3-Clause, com modificações e aprimoramentos substanciais por @kesslerio. O aviso de licença BSD original é preservado no arquivo LICENSE conforme exigido.

Pronto para transformar seu fluxo de trabalho de CRM? Instale o Attio MCP Server hoje e experimente o futuro da automação de CRM com IA!

npm install -g attio-mcp