Attio MCP Server

Servidor MCP de Attio

Un servidor integral del Protocolo de Contexto de Modelos (MCP) para Attio, que proporciona cobertura completa de la superficie CRM. Este servidor permite que asistentes de IA como Claude y ChatGPT interactúen directamente con todo tu espacio de trabajo de Attio mediante lenguaje natural: gestiona Ofertas, Tareas, Listas, Personas, Empresas, Registros y Notas sin recurrir a llamadas API sin procesar.

🎯 ¿Qué es el Servidor MCP de Attio?

Transforma tus flujos de trabajo CRM con automatización impulsada por IA. En lugar de hacer clic en múltiples pantallas, simplemente pide a Claude o ChatGPT que encuentren prospectos, actualicen registros, gestionen pipelines y analicen tus datos usando comandos en lenguaje natural.

🎉 Hito v1.0.0: Cobertura completa de la superficie CRM de Attio con integración total del Modo Desarrollador de ChatGPT.

"Encuentra todas las empresas de IA con más de 50 empleados que no hemos contactado en 30 días y agrégalas a nuestra lista de alcance del primer trimestre"

🚀 Integración del Modo Desarrollador de ChatGPT

⚠️ Smithery Temporalmente No Disponible: Smithery ha cambiado su modelo de implementación para requerir alojamiento externo. Estamos trabajando en el alojamiento de Cloudflare Worker para usuarios de ChatGPT. Mientras tanto, usa Nivel 4 (Cloudflare Worker) para acceso remoto/ChatGPT.

Los usuarios de ChatGPT Pro/Plus pueden acceder al conjunto de herramientas de Attio mediante lenguaje natural usando un Cloudflare Worker autoalojado:

• 🔐 Flujos de Aprobación Integrados: Las anotaciones de seguridad de MCP aprueban automáticamente operaciones de lectura y solicitan aprobación para escrituras
• 🌐 Integración OAuth: OAuth autoalojado mediante implementación de Cloudflare Worker
• 💬 CRM en Lenguaje Natural: Gestiona todo tu espacio de trabajo de Attio a través de IA conversacional
• 📖 Guía de Configuración: Consulta la documentación del Modo Desarrollador de ChatGPT y la Guía de Cloudflare Worker

✨ Características Principales y Estado de Implementación

🎯 Arquitectura de Herramientas Universales (19 Operaciones Universales)

Superficie de Herramientas Enfocada: Consolidamos más de 40 herramientas específicas de recursos en operaciones universales, luego agregamos herramientas de escritura de alta frecuencia con alcance para actualizaciones más seguras de empresas y ofertas.

• Alto Rendimiento: Mejora de velocidad del 89.7% con reducción de memoria de 227KB (PR #483)
• Calidad Empresarial: Puntuación de preparación para producción de 97.15/100 con cero cambios disruptivos
• Arquitectura Limpia: Separación completa de producción y pruebas con patrón de fábrica simulada
• Política de Herramientas con Alcance: Agrega herramientas predeterminadas con alcance solo cuando el flujo de trabajo es frecuente, una escritura genérica puede mutar la clase de objeto incorrecta, y la herramienta con alcance elimina una decisión del modelo en lugar de simplemente renombrar una llamada universal

📊 Estado de Implementación de Características

✅ Cobertura Completa de la Superficie CRM

• Empresas: Búsqueda, Creación, Actualización, Eliminación, Búsqueda Avanzada, Búsqueda de Relaciones
• Personas: Búsqueda, Creación, Actualización, Eliminación, Búsqueda Avanzada, Búsqueda de Relaciones
• Ofertas: Operaciones CRUD completas con mapeo inteligente de campos y validación de etapas
• Tareas: Creación, Actualización, Eliminación, Búsqueda con soporte de múltiples asignados
• Listas: Operaciones CRUD completas, filtrado, filtrado avanzado, gestión de entradas
• Notas: Operaciones de creación y listado para todos los tipos de registros
• Registros: Operaciones CRUD universales en todos los tipos de recursos
• Operaciones por Lote: Creación, Actualización, Eliminación con fragmentación y manejo de errores
• Búsqueda de Contenido: Capacidades de búsqueda universal en notas, tareas y listas
• Navegación de Relaciones: Relaciones bidireccionales empresa↔persona↔oferta
• Filtrado Avanzado: Capacidades de consulta sofisticadas con mapeo inteligente de campos

📊 Gestión de Empresas

• Búsqueda Universal: Encuentra empresas con search_records y search_records_advanced
• Escrituras con Alcance: Crea y actualiza empresas con create_company y update_company
• CRUD Completo: Crea, lee, actualiza y elimina con operaciones de registro universal cuando no hay una herramienta con alcance disponible
• Descubrimiento de Relaciones: Encuentra empresas a través de search_records_by_relationship
• Operaciones por Lote: Procesa cientos de empresas con batch_records
• Información Detallada: Obtén información de contacto, comercial y social con get_record_info

👥 Gestión de Personas

• Búsqueda Universal de Contactos: Encuentra personas por cualquier criterio usando herramientas de búsqueda universal
• Seguimiento de Relaciones: Vincula personas a empresas con search_records_by_relationship
• Línea de Tiempo de Actividad: Rastrea interacciones con search_records_by_content y search_records_by_timeframe
• Filtrado Avanzado: Búsqueda multi-atributo con filtrado universal
• Operaciones Masivas: Gestiona contactos eficientemente con operaciones por lote universales

📋 Gestión de Listas y Pipeline (6 Herramientas + 8 Obsoletas)

• Herramientas Activas: 4 herramientas consolidadas con detección automática de modo (Guía de Migración)
  • filter-list-entries - Filtrado unificado con 4 modos
  • manage-list-entry - Gestión unificada de entradas con 3 modos
  • get-list-entries - Recuperar entradas de lista
  • get-record-list-memberships - Encontrar membresías de lista de un registro
• Herramientas de Configuración de Listas (dedicadas; las universales create_record/update_record rechazan resource_type: "lists"):
  • create-list - Crea listas con controles de acceso de primera clase: workspace_access (full-access | read-and-write | read-only | "null" para una lista privada) y workspace_member_access (concesiones por miembro). Omitir ambos campos de acceso establece por defecto la nueva lista con acceso completo a nivel de espacio de trabajo; las nuevas listas deben mantener al menos un beneficiario con acceso completo.
  • update-list-configuration - Actualiza nombre, campos personalizados y los mismos controles de acceso. Las concesiones a nivel de miembro pueden elevar el acceso por encima del predeterminado del espacio de trabajo, pero nunca reducirlo por debajo de workspace_access.
  • Los errores distinguen plan_gating (el plan del espacio de trabajo no admite la configuración de acceso solicitada) de permission_failure (permisos de token/espacio de trabajo) y unsupported_input (configuración de acceso malformada), cada uno con un siguiente paso sugerido.
• Obsoletas (eliminación en v2.0.0): 8 herramientas heredadas reemplazadas por versiones consolidadas
• Operaciones de Pipeline: Mueve ofertas a través de las etapas de ventas
• Segmentación Inteligente: Crea y gestiona listas de contactos dirigidas
• Filtrado Avanzado: Filtrado complejo de múltiples condiciones con lógica Y/O
• Gestión de Entradas: Agrega, elimina y actualiza membresías de listas
• Seguimiento de Ofertas: Monitorea oportunidades y pipeline de ingresos
• Valores Predeterminados de Ofertas: Etapa, propietario y moneda predeterminados configurables para una creación simplificada de ofertas
• Escrituras de Ofertas con Alcance: Crea y actualiza ofertas con create_deal y update_deal

✅ Gestión de Tareas

• Operaciones Universales de Tareas: Crea, actualiza y gestiona tareas con herramientas universales
• Vinculación de Registros: Asocia tareas con cualquier tipo de registro usando el parámetro resource_type
• Seguimiento de Progreso: Monitorea la finalización con búsqueda y filtrado universales
• Coordinación de Equipos: Optimiza los seguimientos con operaciones universales consistentes

🔧 Capacidades Avanzadas

• Procesamiento por Lote: Maneja operaciones masivas con seguimiento de errores
• Filtrado Mejorado: Filtros de texto, numéricos, de fecha, booleanos y de relaciones con búsqueda por período de tiempo (Problema #475)
• Exportación de Datos: Serialización JSON para integraciones
• Actualizaciones en Tiempo Real: Sincronización de datos en vivo con Attio

🧠 Habilidades de Claude

Potencia el conocimiento de Attio de Claude con habilidades preconstruidas que previenen errores comunes y enseñan mejores prácticas.

Inicio Rápido (resuelve errores de "nombre de campo incorrecto"):

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

Consulta la Documentación de Habilidades para guías completas de configuración y uso.

💬 Indicaciones Preconstruidas (10 Indicaciones)

Atajos inteligentes que ayudan a Claude a trabajar más rápido con tus datos CRM:

• Buscar y Encontrar (5): people_search, company_search, deal_search, meeting_prep, pipeline_health
• Tomar Acciones (4): log_activity, create_task, advance_deal, add_to_list con seguridad de ejecución en seco
• Investigar y Calificar (1): qualify_lead con investigación web automatizada y marcos BANT/CHAMP
• Eficiente en Tokens: 300-700 tokens por indicación con formato consistente
• Descubribles: Claude sugiere automáticamente indicaciones relevantes para tus tareas

Consulta Uso de Indicaciones Preinstaladas para documentación detallada y ejemplos.

🎯 Uso de Indicaciones Preinstaladas

NUEVO: 10 indicaciones MCP preconstruidas para flujos de trabajo de ventas comunes. ¡Sin configuración requerida, solo úsalas!

Indicaciones Disponibles

Ejemplos 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 Universales

Todas las indicaciones de lectura admiten:

• format: table | json | ids (predeterminado: table)
• fields_preset: sales_short | full (predeterminado: sales_short)
• verbosity: brief | normal (predeterminado: brief)

Todas las indicaciones de escritura admiten:

• dry_run: true | false (predeterminado: false) - Previsualiza cambios sin ejecutarlos

Características de Conciencia de Tokens

Las indicaciones incluyen optimización de tokens integrada:

• Guardas de presupuesto: Los prompts se mantienen dentro de los límites de tokens (people_search <500, qualify_lead <400)
• Metadatos de desarrollo: Establezca MCP_DEV_META=true para los conteos de tokens en las respuestas
• Telemetría: Establezca PROMPT_TELEMETRY_ENABLED=true para el registro de uso
• Límites configurables: Anule con la variable de entorno MAX_PROMPT_TOKENS

Para la documentación completa de prompts, consulte docs/prompts/v1-catalog.md.

⚠️ Limitaciones conocidas y notas importantes

Limitaciones actuales

• Filtrado de parámetros de campo: El endpoint de tareas /objects/tasks/attributes tiene limitaciones, manejadas con patrones de respaldo
• Paginación: La paginación de tareas utiliza manejo en memoria debido a restricciones de la API

Compatibilidad de API

• Herramientas universales: Interfaz principal (19 herramientas) - recomendadas para todas las integraciones nuevas
• Herramientas heredadas: Disponibles a través de la variable de entorno DISABLE_UNIVERSAL_TOOLS=true (obsoletas)
• API de listas: Totalmente funcional con operaciones CRUD completas (contrario a alguna documentación desactualizada)

🤝 Compatibilidad con OpenAI MCP

• Listo para modo desarrollador: Cada herramienta ahora publica anotaciones de seguridad MCP (readOnlyHint, destructiveHint) para que el modo desarrollador de OpenAI pueda aprobar automáticamente lecturas y solicitar confirmación para escrituras.
• Acceso completo a herramientas (predeterminado): Las 41 herramientas están expuestas por defecto (26 universales/OpenAI + 12 listas + 3 miembros del espacio de trabajo). NO establezca ATTIO_MCP_TOOL_MODE en la configuración de Smithery para acceso completo.
• Modo solo búsqueda: Para restringir a herramientas de solo lectura (search, fetch, aaa-health-check), configure explícitamente ATTIO_MCP_TOOL_MODE: 'search' en el panel de Smithery cuando el modo desarrollador no esté disponible.
• Guía detallada: Consulte docs/chatgpt-developer-mode.md para variables de entorno, flujos de aprobación y consejos de validación.
• Documentación de usuario: Consulte la documentación del modo desarrollador de ChatGPT para un recorrido completo de los flujos de aprobación e instrucciones de configuración.

Consideraciones de rendimiento

• Operaciones por lotes: Optimizadas con fragmentación, limitación de velocidad y recuperación de errores
• Conjuntos de datos grandes: Paginación automática y filtrado de campos para un rendimiento óptimo
• Limitación de velocidad: Protección integrada contra límites de velocidad de API con retroceso exponencial

Para solución de problemas detallada y soluciones, consulte TROUBLESHOOTING.md y Problemas de GitHub.

🎯 Filtros de búsqueda avanzados

Construya consultas CRM potentes con filtrado AND/OR de múltiples criterios. Consulte la Guía de búsqueda avanzada para ejemplos completos y referencia de operadores.

🚀 Instalación

⚠️ IMPORTANTE: Nombre correcto del paquete

El nombre del paquete npm es attio-mcp (no attio-mcp-server). El repositorio de GitHub se llama attio-mcp-server, pero el paquete npm fue renombrado a attio-mcp en junio de 2025. Instalar attio-mcp-server le dará una versión desactualizada v0.0.2 con solo 4 herramientas heredadas.

Compatibilidad de clientes

Elija su método de instalación:

• La mayoría de usuarios: Use Nivel 1 (Instaladores de shell) - un comando, configuración automática
• Usuarios avanzados: Use Nivel 2 (Manual) - control total sobre la configuración
• ChatGPT/Teams/Enterprise: Use Nivel 3 (Cloudflare Worker) - autohospedado, OAuth multiusuario

Nivel 1: Instaladores de shell

Mejor para: Desarrolladores que prefieren instalaciones locales con configuración automática.

Scripts de un comando que instalan attio-mcp y configuran su cliente automáticamente.

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

Estos scripts:

• Instalarán el paquete npm attio-mcp globalmente (si es necesario)
• Harán una copia de seguridad de los archivos de configuración existentes
• Solicitarán su clave de API de Attio
• Configurarán el servidor MCP para su cliente
• Imprimirán los siguientes pasos e instrucciones de reinicio

Nivel 2: Configuración manual

Mejor para: Usuarios avanzados que prefieren control total o usan clientes no compatibles.

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

Nivel 3: Cloudflare Worker (Implementación remota)

Mejor para: Equipos que necesitan OAuth centralizado, acceso multiusuario, acceso móvil o ejecutar MCP sin instalación local.

Implemente su propio servidor MCP de Attio en Cloudflare Workers con soporte completo de OAuth 2.1.

Acceso móvil: Con un servidor MCP remoto, puede usar las herramientas de Attio desde:

• Aplicación móvil de ChatGPT (iOS/Android)
• Aplicación móvil de Claude (iOS/Android)
• Cualquier navegador en cualquier dispositivo

Características de Cloudflare Worker

Implementación 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

Configuración del cliente

Después de la implementación, configure su cliente con la URL de su Worker:

• Claude.ai: Configuración → Conectores → Agregue la URL de su Worker
• ChatGPT: Configuración → Conectores → Modo desarrollador → Agregue la URL del Worker

Consulte la Guía de implementación de Cloudflare Worker para:

• Configuración completa de OAuth 2.1 con Attio
• Configuración de cifrado de tokens
• Lista de verificación de implementación en producción
• Guía de solución de problemas

🆕 Novedades en v1.4.0

Características principales

• 🎯 Generador de habilidades de esquema de espacio de trabajo (#983) - Genere automáticamente habilidades de Claude desde el esquema de su espacio de trabajo de Attio para nombres de campos y opciones sin errores
• 🔍 Transformador de campos de selección (#1019) - Coincidencia sin distinción de mayúsculas y minúsculas, coincidencia parcial y paso directo de UUID para campos de selección/estado
• 🛠️ Meta-habilidad del generador de habilidades de Attio (#1020) - Meta-habilidad para documentación automática del espacio de trabajo
• 📚 Habilidad de guía de uso universal (#1018) - Patrones de flujo de trabajo y prevención de errores elaborados a mano
• ⚙️ Herramienta get_record_attribute_options (#975) - Obtenga opciones válidas para campos de selección/estado con mensajes de error mejorados
• 📞 Validación de teléfono (#951) - Soporte integrado de validación de números de teléfono
• ⏱️ Retraso configurable de obtención de opciones - Control de limitación de velocidad mediante la bandera --option-fetch-delay

Mejoras principales

• 🏷️ Nombres de herramientas compatibles con MCP (#1039) - Todas las herramientas ahora usan snake_case, nombres con verbo primero (los nombres antiguos funcionan mediante alias hasta v2.0.0)
• 🎨 Nombres de visualización de objetos personalizados (#1017) - Obtenga nombres de visualización directamente de la API de Attio
• 📖 Patrones de integración divididos (#1023) - Patrones de descubrimiento progresivo por caso de uso
• 💡 Mensajes de error de atributos mejorados (#975) - Sugerencias de distancia de Levenshtein para errores tipográficos

Correcciones críticas

• 📝 Se preservan los saltos de línea en el contenido de notas (#1052)
• 👤 Se corrigió la visualización "Sin nombre" en la búsqueda de personas (#1051)
• ✅ Persistencia de campos de selección (#1045)
• 🔗 Auto-transformación de referencias de registros (#997)
• 📊 Auto-transformación de matrices de selección múltiple (#992)
• 🛡️ Validación de atributos complejos (#991)
• ⚠️ Advertencias falsas de persistencia de campos (#995)
• 📦 Fijación de dependencias del SDK (#1025)
• 💼 Validación de etapa de trato/UTM (#1043)
• 📍 Auto-normalización de campos de ubicación (#987)

Mejoras internas

• Refactorización del sistema de alias de herramientas (#1041) - Constantes seguras de tipos con generación basada en patrones
• Patrón de estrategia para manejadores de errores CRUD (#1001)
• Obtención de metadatos consolidada (#984)
• Modularización de UniversalUpdateService (#984)
• Cambio de nombre del tipo de transformación de selección (#1055) - select_title_to_array para mayor claridad

🔄 Guía de migración

¿Actualizando desde v1.3.x o anterior? Los nombres de las herramientas han cambiado para seguir las convenciones de nomenclatura de MCP.

Los nombres antiguos aún funcionan mediante alias compatibles con versiones anteriores, pero se eliminarán en v2.0.0 (Q1 2026).

Cambios de nombres de herramientas

Acción requerida: Actualice sus integraciones para usar los nuevos nombres de herramientas antes del Q1 2026. Consulte MIGRATION-GUIDE.md para la tabla de migración completa.

⚡ Inicio rápido

Requisitos previos

• Node.js (v18 o superior)
• Clave de API de Attio (Obtenga una aquí) o token de acceso OAuth
• ID del espacio de trabajo de Attio

🔐 Opciones de autenticación

El servidor admite dos métodos de autenticación: ambos usan el mismo esquema de token Bearer:

Nota: Si ambos están configurados, ATTIO_API_KEY tiene prioridad.

Usuarios de OAuth: Para una configuración detallada, incluido el flujo PKCE y la renovación de tokens, consulta la Guía de autenticación OAuth.

1. Establecer variables de entorno

# 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. Probar la instalación

# Test the MCP server
attio-mcp --help

# Discover your Attio workspace attributes
attio-discover attributes

3. 🎯 CRÍTICO: Configurar los mapeos de campos

El servidor MCP utiliza archivos de mapeo de campos para traducir entre el lenguaje natural y los nombres de campos de la API de Attio. Esta configuración es esencial para un funcionamiento correcto.

Configuración 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

Archivos de configuración (en configs/runtime/mappings/)

• default.json - Campos CRM estándar de Attio (se cargan primero, no editar)
• sample.json - Ejemplos con plantillas de campos personalizados (copiar desde aquí, no se usa en tiempo de ejecución)
• user.json - Anulaciones específicas de TU espacio de trabajo (se fusionan sobre default.json)

💡 Información clave: user.json se fusiona sobre default.json, por lo que solo debes incluir anulaciones y adiciones. No dupliques mapeos que ya existan en default.json.

Cómo funciona la fusión de configuración

El servidor MCP carga la configuración en este orden:

1. default.json - Contiene todos los campos estándar de Attio (Nombre, Descripción, Equipo, etc.)
2. user.json - Tus adiciones/anulaciones personalizadas se fusionan encima

Ejemplo: Si default.json tiene "Name": "name" y tu user.json también tiene "Name": "name", eso es un desperdicio de tokens. Solo incluye campos que sean:

• Campos personalizados nuevos (que no estén en default.json)
• Mapeos diferentes (que anulen el comportamiento predeterminado)

Ejemplo optimizado 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"
    }
  }
}

✅ Correcto: Solo campos personalizados/anulaciones
❌ Desperdicio: Duplicar campos estándar de default.json

⚠️ Sin una configuración de mapeo adecuada, el servidor MCP puede no funcionar correctamente con tus campos y listas personalizados.

Siguiente: Verifica que tus mapeos de campos funcionen probando con Claude:

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

4. Configurar Claude Desktop

Añade a la configuración MCP de tu Claude Desktop:

Encontrar los IDs requeridos

Correo del propietario del acuerdo (para los propietarios predeterminados de acuerdos): El ATTIO_DEFAULT_DEAL_OWNER debe establecerse con la dirección de correo electrónico del miembro del espacio de trabajo que debe ser propietario de los nuevos acuerdos por defecto. Normalmente es tu propia dirección de correo o la del líder de tu equipo de ventas.

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

Nota: El sistema resolverá automáticamente las direcciones de correo a referencias de miembros del espacio de trabajo al crear acuerdos.

Etapas de acuerdos: Las etapas de acuerdos son específicas de tu espacio de trabajo. Consulta la configuración de tu espacio de trabajo en Attio o usa el comando discover-attributes para encontrar las etapas disponibles para acuerdos.

{
  "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"
      }
    }
  }
}

🌟 Ejemplos de casos de uso

Para equipos de ventas

"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 equipos 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 éxito del 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 operaciones de datos

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

🔐 Seguridad y privacidad

• Autenticación API segura: Autenticación con clave API estándar de la industria
• Sin almacenamiento de datos: Paso directo de API sin retención local de datos
• Código abierto: Transparencia total con licencia Apache 2.0
• Opción local (on-premises): Implementa en tu propia infraestructura
• Procedencia npm: Publicado con procedencia Sigstore — cada versión está vinculada criptográficamente a la compilación de GitHub Actions y al commit del código fuente

Verificación de la cadena de suministro

Este paquete se publica con procedencia npm, creando una cadena verificable desde el código fuente hasta el artefacto publicado. Verifica una versión:

# 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 una máxima protección de la cadena de suministro, instala con pnpm v10+, que aplica:

• trustPolicy: no-downgrade — bloquea versiones publicadas con credenciales más débiles que versiones anteriores
• minimumReleaseAge — período de espera antes de que se puedan instalar nuevas versiones

📚 Documentación

La documentación completa está disponible en el directorio docs:

Herramientas universales (recomendado)

⚠️ Nota: La documentación de herramientas universales se está actualizando para coincidir con la implementación más reciente. Usa la API directamente o consulta el código fuente para obtener las definiciones de interfaz más precisas.

• Descripción general de la API - Conceptos y patrones de API de alto nivel
• Código fuente de herramientas universales - Referencia de implementación actual
• Esquemas de herramientas - Definiciones de parámetros y validación

Primeros pasos

• Instalación y configuración
• Configuración de Claude Desktop
• Guía de solución de problemas

Configuración

• Configuración del filtro de advertencias - Comprensión de discrepancias cosméticas vs. semánticas, presupuestos de ESLint y estrategias de supresión
• Configuración de verificación de campos - Verificación de persistencia de campos y ajustes de validación
• Configuración de puntuación de búsqueda - Variables de entorno para puntuación de relevancia, caché y validación de operadores

Referencia de la API

📋 Estado de implementación: Estos documentos describen los endpoints de la API de Attio. Para el uso de herramientas MCP, consulta la documentación de herramientas universales anterior.

• Descripción general de la API - Conceptos generales de la API de Attio
• API de empresas - Endpoints de registros de empresas ✅ Totalmente implementado mediante herramientas universales
• API de personas - Endpoints de registros de personas ✅ Totalmente implementado mediante herramientas universales
• API de listas - Endpoints de gestión de listas ✅ Totalmente implementado
• API de notas - Endpoints de notas ✅ Implementación básica
• API de tareas - Endpoints de tareas ✅ Implementado mediante herramientas universales

Temas avanzados

• Operaciones por lotes - Operaciones masivas ✅ Implementado con fragmentación
• Filtrado avanzado - Consultas complejas ✅ Implementado
• Manejo de errores - Patrones de errores ✅ Manejo de errores mejorado
• Extender MCP - Guía de personalización

Implementación

• Guía de Docker
• Mejores prácticas de seguridad

🛠 Desarrollo

Configurar el entorno de desarrollo

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

Desarrollo con Smithery CLI

Para desarrollo y pruebas locales con Smithery Playground:

npm run dev  # Opens Smithery Playground with local server

Consulta docs/deployment/smithery-cli-setup.md para obtener una configuración detallada del desarrollo con Smithery CLI.

Pruebas

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 pruebas E2E/integración, crea .env con tu ATTIO_API_KEY. Consulta la Guía de pruebas para una configuración detallada.

Scripts disponibles

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

🤝 Contribuciones

¡Agradecemos las contribuciones! Consulta nuestras Directrices de contribución para obtener detalles sobre:

• Añadir nuevas herramientas y funciones
• Mejorar la documentación
• Reportar errores y solicitar funciones
• Pruebas y aseguramiento de calidad

📈 ¿Qué sigue?

Esta versión inicial proporciona una base sólida para la automatización de CRM.

🔗 Enlaces

• Paquete NPM: https://www.npmjs.com/package/attio-mcp
• Repositorio de GitHub: https://github.com/kesslerio/attio-mcp-server
• Problemas y soporte: https://github.com/kesslerio/attio-mcp-server/issues
• Versiones: https://github.com/kesslerio/attio-mcp-server/releases
• Documentación de Attio: https://developers.attio.com/

📄 Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0 — consulta el archivo LICENSE para más detalles.

Atribución del trabajo original: Este proyecto se basa en el trabajo inicial de @hmk bajo la licencia BSD-3-Clause, con modificaciones y mejoras sustanciales de @kesslerio. El aviso de licencia BSD original se conserva en el archivo LICENSE según lo requerido.

¿Listo para transformar tu flujo de trabajo de CRM? Instala Attio MCP Server hoy y experimenta el futuro de la automatización de CRM con IA.

npm install -g attio-mcp