Attio MCP Server

A comprehensive Model Context Protocol (MCP) server for Attio, providing complete CRM surface coverage. This server enables AI assistants like Claude and ChatGPT to interact directly with your entire Attio workspace through natural language—manage Deals, Tasks, Lists, People, Companies, Records, and Notes without falling back to raw API calls.

Transform your CRM workflows with AI-powered automation. Instead of clicking through multiple screens, simply ask Claude or ChatGPT to find prospects, update records, manage pipelines, and analyze your data using natural language commands.

🎉 v1.0.0 Milestone: Complete Attio CRM surface coverage with full ChatGPT Developer Mode integration.

"Find all AI companies with 50+ employees that we haven't contacted in 30 days and add them to our Q1 outreach list"

⚠️ Smithery Temporarily Unavailable: Smithery has changed their deployment model to require external hosting. We're working on Cloudflare Worker hosting for ChatGPT users. In the meantime, use Tier 4 (Cloudflare Worker) for ChatGPT/remote access.

ChatGPT Pro/Plus users can access the Attio toolset through natural language using a self-hosted Cloudflare Worker:

• 🔐 Built-in Approval Flows: MCP safety annotations auto-approve read operations, request approval for writes
• 🌐 OAuth Integration: Self-hosted OAuth via Cloudflare Worker deployment
• 💬 Natural Language CRM: Manage your entire Attio workspace through conversational AI
• 📖 Setup Guide: See ChatGPT Developer Mode docs and Cloudflare Worker Guide

68% Tool Reduction: Consolidated 40+ resource-specific tools into 14 universal operations for consistent, powerful CRM management.

• High Performance: 89.7% speed improvement with 227KB memory reduction (PR #483)
• Enterprise Quality: 97.15/100 production readiness score with zero breaking changes
• Clean Architecture: Complete production-test separation with mock factory pattern

• Companies: Search, Create, Update, Delete, Advanced Search, Relationship Search
• People: Search, Create, Update, Delete, Advanced Search, Relationship Search
• Deals: Full CRUD operations with intelligent field mapping and stage validation
• Tasks: Create, Update, Delete, Search with multi-assignee support
• Lists: Full CRUD operations, filtering, advanced filtering, entry management
• Notes: Create and list operations for all record types
• Records: Universal CRUD operations across all resource types
• Batch Operations: Create, Update, Delete with chunking and error handling
• Content Search: Universal search capabilities across notes, tasks, and lists
• Relationship Navigation: Bidirectional company↔person↔deal relationships
• Advanced Filtering: Sophisticated query capabilities with intelligent field mapping

• Universal Search: Find companies with search_records and search_records_advanced
• Full CRUD: Create, read, update, and delete with universal record operations
• Relationship Discovery: Find companies through search_records_by_relationship
• Batch Operations: Process hundreds of companies with batch_records
• Detailed Information: Get contact, business, and social info with get_record_info

• Universal Contact Search: Find people by any criteria using universal search tools
• Relationship Tracking: Link people to companies with search_records_by_relationship
• Activity Timeline: Track interactions with search_records_by_content and search_records_by_timeframe
• Advanced Filtering: Multi-attribute search with universal filtering
• Bulk Operations: Efficiently manage contacts with universal batch operations

• Active Tools: 4 consolidated tools with auto-mode detection (Migration Guide)
  • filter-list-entries - Unified filtering with 4 modes
  • manage-list-entry - Unified entry management with 3 modes
  • get-list-entries - Retrieve list entries
  • get-record-list-memberships - Find record's list memberships
• Deprecated (v2.0.0 removal): 8 legacy tools replaced by consolidated versions
• Pipeline Operations: Move deals through sales stages
• Smart Segmentation: Create and manage targeted contact lists
• Advanced Filtering: Complex multi-condition filtering with AND/OR logic
• Entry Management: Add, remove, and update list memberships
• Deal Tracking: Monitor opportunities and revenue pipeline
• Deal Defaults: Configurable default stage, owner, and currency for streamlined deal creation

• Universal Task Operations: Create, update, and manage tasks with universal tools
• Record Linking: Associate tasks with any record type using resource_type parameter
• Progress Tracking: Monitor completion with universal search and filtering
• Team Coordination: Streamline follow-ups with consistent universal operations

• Batch Processing: Handle bulk operations with error tracking
• Enhanced Filtering: Text, numeric, date, boolean, and relationship filters with timeframe search (Issue #475)
• Data Export: JSON serialization for integrations
• Real-time Updates: Live data synchronization with Attio

Supercharge Claude's Attio knowledge with pre-built skills that prevent common errors and teach best practices.

Quick Start (solves "wrong field name" errors):

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

See Skills Documentation for complete setup and usage guides.

Intelligent shortcuts that help Claude work faster with your CRM data:

• Search & Find (5): people_search, company_search, deal_search, meeting_prep, pipeline_health
• Take Actions (4): log_activity, create_task, advance_deal, add_to_list with dry-run safety
• Research & Qualify (1): qualify_lead with automated web research and BANT/CHAMP frameworks
• Token-efficient: 300-700 tokens per prompt with consistent formatting
• Discoverable: Claude automatically suggests relevant prompts for your tasks

See Using Out-of-the-Box Prompts for detailed documentation and examples.

NEW: 10 pre-built MCP prompts for common Sales workflows. No setup required—just use them!

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

All read prompts support:

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

All write prompts support:

• dry_run: true | false (default: false) - Preview changes without executing

Prompts include built-in token optimization:

• Budget Guards: Prompts stay within token limits (people_search <500, qualify_lead <400)
• Dev Metadata: Set MCP_DEV_META=true for token counts in responses
• Telemetry: Set PROMPT_TELEMETRY_ENABLED=true for usage logging
• Configurable Limits: Override with MAX_PROMPT_TOKENS environment variable

For complete prompt documentation, see docs/prompts/v1-catalog.md.

• Field Parameter Filtering: Tasks endpoint /objects/tasks/attributes has limitations, handled with fallback patterns
• Pagination: Tasks pagination uses in-memory handling due to API constraints

• Universal Tools: Primary interface (14 tools) - recommended for all new integrations
• Legacy Tools: Available via DISABLE_UNIVERSAL_TOOLS=true environment variable (deprecated)
• Lists API: Fully functional with complete CRUD operations (contrary to some outdated documentation)

• Developer Mode Ready: Every tool now publishes MCP safety annotations (readOnlyHint, destructiveHint) so OpenAI Developer Mode can auto-approve reads and request confirmation for writes.
• Full Tool Access (Default): All 35 tools are exposed by default (21 universal + 11 list + 3 workspace member). Do NOT set ATTIO_MCP_TOOL_MODE in Smithery configuration for full access.
• Search-Only Mode: To restrict to read-only tools (search, fetch, aaa-health-check), explicitly configure ATTIO_MCP_TOOL_MODE: 'search' in Smithery dashboard when Developer Mode is unavailable.
• Detailed Guide: See docs/chatgpt-developer-mode.md for environment variables, approval flows, and validation tips.
• User Documentation: See the ChatGPT Developer Mode docs for a complete walkthrough of approval flows and setup instructions.

• Batch Operations: Optimized with chunking, rate limiting, and error recovery
• Large Datasets: Automatic pagination and field filtering for optimal performance
• Rate Limiting: Built-in protection against API rate limits with exponential backoff

For detailed troubleshooting and solutions, see TROUBLESHOOTING.md and GitHub Issues.

Build powerful CRM queries with multi-criteria AND/OR filtering. See the Advanced Search Guide for complete examples and operator reference.

⚠️ IMPORTANT: Correct Package Name

The npm package name is attio-mcp (not attio-mcp-server). The GitHub repository is named attio-mcp-server, but the npm package was renamed to attio-mcp in June 2025. Installing attio-mcp-server will give you an outdated v0.0.2 release with only 4 legacy tools.

Choose your installation method:

• Most users: Use Tier 1 (Shell Installers) - one command, automatic setup
• Power users: Use Tier 2 (Manual) - full control over configuration
• ChatGPT/Teams/Enterprise: Use Tier 3 (Cloudflare Worker) - self-hosted, multi-user OAuth

Best for: Developers who prefer local installations with automatic configuration.

One-command scripts that install attio-mcp and configure your client automatically.

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

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

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

These scripts will:

• Install attio-mcp npm package globally (if needed)
• Backup existing configuration files
• Prompt for your Attio API key
• Configure the MCP server for your client
• Print next steps and restart instructions

Best for: Power users who prefer full control or use unsupported clients.

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

Best for: Teams needing centralized OAuth, multi-user access, mobile access, or running MCP without local installation.

Deploy your own Attio MCP server on Cloudflare Workers with full OAuth 2.1 support.

Mobile Access: With a remote MCP server, you can use Attio tools from:

• ChatGPT mobile app (iOS/Android)
• Claude mobile app (iOS/Android)
• Any browser on any device

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

After deployment, configure your client with your Worker URL:

• Claude.ai: Settings → Connectors → Add your Worker URL
• ChatGPT: Settings → Connectors → Developer Mode → Add Worker URL

See Cloudflare Worker Deployment Guide for:

• Complete OAuth 2.1 setup with Attio
• Token encryption configuration
• Production deployment checklist
• Troubleshooting guide

• 🎯 Workspace Schema Skill Generator (#983) - Auto-generate Claude Skills from your Attio workspace schema for error-free field names and options
• 🔍 Select-field Transformer (#1019) - Case-insensitive matching, partial matching, and UUID pass-through for select/status fields
• 🛠️ Attio Skill Generator Meta-skill (#1020) - Meta-skill for automatic workspace documentation
• 📚 Universal Usage Guide Skill (#1018) - Hand-crafted workflow patterns and error prevention
• ⚙️ get_record_attribute_options tool (#975) - Get valid options for select/status fields with enhanced error messages
• 📞 Phone validation (#951) - Built-in phone number validation support
• ⏱️ Configurable option fetch delay - Rate limiting control via --option-fetch-delay flag

• 🏷️ MCP-compliant tool naming (#1039) - All tools now use snake_case, verb-first naming (old names work via aliases until v2.0.0)
• 🎨 Custom object display names (#1017) - Fetch display names directly from Attio API
• 📖 Split integration patterns (#1023) - Progressive discovery patterns by use case
• 💡 Enhanced attribute error messages (#975) - Levenshtein distance suggestions for typos

• 📝 Note content line breaks preserved (#1052)
• 👤 People search "Unnamed" display fixed (#1051)
• ✅ Select field persistence (#1045)
• 🔗 Record-reference auto-transformation (#997)
• 📊 Multi-select array auto-transformation (#992)
• 🛡️ Complex attribute validation (#991)
• ⚠️ Field persistence false warnings (#995)
• 📦 SDK dependency pinning (#1025)
• 💼 Deal stage/UTM validation (#1043)
• 📍 Location field auto-normalization (#987)

• Tool alias system refactoring (#1041) - Type-safe constants with pattern-based generation
• Strategy Pattern for CRUD error handlers (#1001)
• Consolidated metadata fetching (#984)
• UniversalUpdateService modularization (#984)
• Select transformation type rename (#1055) - select_title_to_array for clarity

Upgrading from v1.3.x or earlier? Tool names have changed to follow MCP naming conventions.

Old names still work via backward-compatible aliases, but will be removed in v2.0.0 (Q1 2026).

Action Required: Update your integrations to use new tool names before Q1 2026. See MIGRATION-GUIDE.md for the complete migration table.

• Node.js (v18 or higher)
• Attio API Key (Get one here) or OAuth access token
• Attio Workspace ID

The server supports two authentication methods—both use the same Bearer token scheme:

Note: If both are set, ATTIO_API_KEY takes precedence.

OAuth Users: For detailed setup including PKCE flow and token refresh, see OAuth Authentication Guide.

# 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

# Test the MCP server
attio-mcp --help

# Discover your Attio workspace attributes
attio-discover attributes

The MCP server uses field mapping files to translate between natural language and Attio's API field names. This configuration is essential for proper operation.

# 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

• default.json - Standard Attio CRM fields (loaded first, don't edit)
• sample.json - Examples with custom field templates (copy from this, not used at runtime)
• user.json - YOUR workspace-specific overrides (merged on top of default.json)

💡 Key Insight: user.json is merged on top of default.json, so only include overrides and additions. Don't duplicate mappings that already exist in default.json.

The MCP server loads configuration in this order:

1. default.json - Contains all standard Attio fields (Name, Description, Team, etc.)
2. user.json - Your custom additions/overrides are merged on top

Example: If default.json has "Name": "name" and your user.json also has "Name": "name", that's wasted tokens. Only include fields that are:

• New custom fields (not in default.json)
• Different mappings (overriding default behavior)