The Attio MCP Server provides a Model Context Protocol (MCP) interface for AI-powered CRM automation, enabling natural language interaction with your Attio workspace.
Universal Record Management: Perform comprehensive CRUD operations (create, update, delete, retrieve) across all record types including Companies, People, Deals, Tasks, Lists, and Notes using consistent universal tools
Advanced Search & Filtering: Execute sophisticated queries with universal search, content search, timeframe search, relationship-based search, and advanced multi-condition filters with AND/OR logic
Batch Operations: Efficiently perform bulk create, update, delete, get, and search operations across multiple records
List & Pipeline Management: Create and manage CRM lists, sales pipelines, and lead stages; add/remove records and update list entry attributes like deal stages
Attribute Discovery: Identify and retrieve available fields and categories for any resource type to align with your workspace structure
Workspace Integration: List, search, and retrieve workspace members for task assignments and deal ownership
AI Assistant Integration: Seamlessly integrate with Claude, ChatGPT (Developer Mode), and other AI assistants with built-in MCP safety annotations for automated approval of read operations and confirmation for write operations
Robust Performance: Benefit from optimized operations, automatic pagination, built-in rate limiting, and chunking for large datasets
Custom Field Mapping: Configure custom field and list mappings to align natural language commands with your unique Attio workspace
Server Health Check: Verify server status without requiring credentials using the
aaa-health-check
tool
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.
🎯 What is Attio MCP Server?
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"
🚀 NEW: ChatGPT Developer Mode Integration
v1.0.0 introduces full ChatGPT compatibility! ChatGPT Pro/Plus users can now access the entire Attio toolset through natural language via Smithery marketplace.
🔐 Built-in Approval Flows: MCP safety annotations auto-approve read operations, request approval for writes
🌐 OAuth Integration: Seamless authentication via
https://server.smithery.ai/@kesslerio/attio-mcp-server/mcp
💬 Natural Language CRM: Manage your entire Attio workspace through conversational AI
📖 Setup Guide: See ChatGPT Developer Mode docs for complete configuration
✨ Core Features & Implementation Status
🎯 Universal Tools Architecture (14 Tools)
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
📊 Feature Implementation Status
✅ Complete CRM Surface Coverage
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
📊 Company Management
Universal Search: Find companies with
search-records
andadvanced-search
Full CRUD: Create, read, update, and delete with universal record operations
Relationship Discovery: Find companies through
search-by-relationship
Batch Operations: Process hundreds of companies with
batch-operations
Detailed Information: Get contact, business, and social info with
get-detailed-info
👥 People Management
Universal Contact Search: Find people by any criteria using universal search tools
Relationship Tracking: Link people to companies with
search-by-relationship
Activity Timeline: Track interactions with
search-by-content
andsearch-by-timeframe
Advanced Filtering: Multi-attribute search with universal filtering
Bulk Operations: Efficiently manage contacts with universal batch operations
📋 Lists & Pipeline Management (11 Tools)
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
✅ Task Management
Universal Task Operations: Create, update, and manage tasks with universal tools
Record Linking: Associate tasks with any record type using
resource_type
parameterProgress Tracking: Monitor completion with universal search and filtering
Team Coordination: Streamline follow-ups with consistent universal operations
🔧 Advanced Capabilities
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
💬 Pre-Built Prompts (10 Prompts)
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.
🎯 Using Out-of-the-Box Prompts
NEW: 10 pre-built MCP prompts for common Sales workflows. No setup required—just use them!
Available Prompts
Prompt | Description | Key Arguments | Example |
| Find people by title, company, territory |
,
,
| Find AE in fintech, SF |
| Query companies by domain, segment, plan |
,
,
| Find SaaS companies >100 employees |
| Filter deals by owner, stage, value, close date |
,
,
| Find deals >$50k closing Q1 |
| Log calls/meetings/emails to records |
,
,
,
| Log call with Nina at Acme |
| Create tasks with natural language due dates |
,
,
,
| Create task: Follow up tomorrow |
| Move deal to target stage with next action |
,
,
,
| Advance deal to "Proposal Sent" |
| Add records to a List by name or ID |
,
,
| Add 5 companies to Q1 Outreach |
| Research lead with web + BANT/CHAMP scoring |
,
,
,
| Qualify Acme Corp with BANT |
| 360° prep: notes, tasks, deals, agenda |
,
,
| Prep for meeting with Acme CEO |
| Weekly snapshot: created/won/slipped + risks |
,
,
| Pipeline health for @me last 30d |
Quick Examples
Universal Arguments
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
Token Awareness Features
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 responsesTelemetry: Set
PROMPT_TELEMETRY_ENABLED=true
for usage loggingConfigurable Limits: Override with
MAX_PROMPT_TOKENS
environment variable
For complete prompt documentation, see docs/prompts/v1-catalog.md.
⚠️ Known Limitations & Important Notes
Current Limitations
Field Parameter Filtering: Tasks endpoint
/objects/tasks/attributes
has limitations, handled with fallback patternsPagination: Tasks pagination uses in-memory handling due to API constraints
API Compatibility
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)
🤝 OpenAI MCP Compatibility
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.Search Compatibility Surface: The
search
andfetch
tools remain available for OpenAI's baseline MCP support. SetATTIO_MCP_TOOL_MODE=search
to expose only these read-only endpoints (plusaaa-health-check
) when Developer Mode is unavailable.Default Behaviour: With
ATTIO_MCP_TOOL_MODE
unset, the full universal tool set is exposed—matching Claude’s experience—while OpenAI users still see the compatibility wrappers.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.
Performance Considerations
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.
🎯 Mastering Advanced Search Filters
The Power Behind Precise CRM Queries - Stop wrestling with complex data searches. Our advanced filtering system lets you find exactly what you need with surgical precision.
"Find all AI companies with 50+ employees that we haven't contacted in 30 days and add them to our Q1 outreach list" - This kind of complex query is exactly what advanced search filters excel at.
🏗️ Filter Architecture
Every advanced search follows this proven pattern that's been battle-tested across thousands of CRM queries:
⚡ Real-World Examples
🔍 Single Criteria Search
🎯 Multi-Criteria Power Search (AND Logic)
🚀 Flexible OR Logic
🧠 Smart Filter Operators
Operator | Perfect For | Example Use Case |
| Text searches | Finding companies with "Tech" in name |
| Exact matches | Specific industry classification |
| Prefix searches | Companies beginning with "Acme" |
| Suffix searches | Companies ending with "Inc" |
| Numerical analysis | Companies with 100+ employees |
| Size filtering | Startups under 50 people |
| Data cleanup | Find records missing key information |
| Completeness checks | Records with populated fields |
💡 Pro Tips for Different Teams
🎯 Sales Teams - Use these field combinations:
Companies:
name
,industry
,employee_count
,website
,location
People:
full_name
,job_title
,email
,company
📈 Marketing Teams - Focus on engagement fields:
Activity tracking:
last_interaction
,email_status
,campaign_response
Segmentation:
industry
,company_size
,location
,engagement_score
✅ Customer Success - Monitor health metrics:
Account health:
renewal_date
,support_tickets
,usage_metrics
Risk indicators:
last_contact
,satisfaction_score
,contract_value
🚨 Avoid These Common Mistakes
❌ Wrong (Flat object structure):
✅ Correct (Nested array structure):
🔧 Quick Troubleshooting
Getting "Filters must include a 'filters' array property"?
✅ Ensure your filters object contains a
filters
array✅ Each array item needs
attribute
,condition
, andvalue
✅ The
attribute
must be an object with aslug
property✅ Double-check your JSON structure matches the examples above
💬 Pro Tip: Start with simple single-filter searches, then build complexity once you're comfortable with the structure.
🏆 Latest Updates - Critical Issues Resolved
✅ 100% Integration Test Pass Rate Achieved - All critical API contract violations and build issues have been resolved:
Recently Fixed Issues (August 2025)
P0 Critical API Failures: Fixed response data structure handling for robust fallback patterns
Build Compilation Errors: Created missing enhanced-validation module and resolved TypeScript compilation
E2E Test Implementation: Fixed JSON truncation, resource mappings, and email validation consistency
Field Parameter Filtering: Resolved tasks attribute handling with special case for missing
/objects/tasks/attributes
endpointEmail Validation Consistency: Fixed batch validation and create/update operation alignment
Pagination System: Documented tasks pagination limitation with in-memory handling workaround
Test Status
Integration Tests: 15/15 passing (100% pass rate)
Build Status: All TypeScript compilation successful
API Contract: All violations resolved with robust error handling
See TROUBLESHOOTING.md for detailed solutions to these resolved issues.
🚀 Installation
Installing via Smithery
To install Attio CRM Integration Server for Claude Desktop automatically via Smithery:
Option 1: NPM (Recommended)
Option 2: One-Command Script Installation
Option 3: Manual Installation
⚡ Quick Start
Prerequisites
Node.js (v18 or higher)
Attio API Key (Get one here)
Attio Workspace ID
1. Set Environment Variables
2. Test the Installation
3. 🎯 CRITICAL: Configure Field Mappings
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.
Quick Setup
Configuration Files (in configs/runtime/mappings/
)
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 ofdefault.json
, so only include overrides and additions. Don't duplicate mappings that already exist indefault.json
.
How Configuration Merging Works
The MCP server loads configuration in this order:
default.json
- Contains all standard Attio fields (Name, Description, Team, etc.)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)
Optimized user.json Example
✅ Good: Only custom/override fields
❌ Wasteful: Duplicating standard fields from default.json
⚠️ Without proper mapping configuration, the MCP server may not work correctly with your custom fields and lists.
Next: Verify your field mappings work by testing with Claude:
4. Configure Claude Desktop
Add to your Claude Desktop MCP configuration:
Finding Required IDs
Deal Owner Email (for deal owner defaults):
The ATTIO_DEFAULT_DEAL_OWNER
should be set to the email address of the workspace member who should own new deals by default. This is typically your own email address or the email address of your sales team lead.
Note: The system will automatically resolve email addresses to workspace member references when creating deals.
Deal Stages:
Deal stages are specific to your workspace. Check your Attio workspace settings or use the discover-attributes
command to find available stages for deals.
🌟 Example Use Cases
For Sales Teams
For Marketing Teams
For Customer Success
For Data Operations
🔐 Security & Privacy
Secure API Authentication: Industry-standard API key authentication
No Data Storage: Direct API passthrough with no local data retention
Open Source: Full transparency with Apache 2.0 license
Optional On-Premises: Deploy in your own infrastructure
📚 Documentation
Comprehensive documentation is available in the docs directory:
Universal Tools (Recommended)
⚠️ Note: Universal tools documentation is currently being updated to match the latest implementation. Use the API directly or check the source code for the most accurate interface definitions.
API Overview - High-level API concepts and patterns
Universal Tools Source - Current implementation reference
Tool Schemas - Parameter definitions and validation
Getting Started
API Reference
📋 Implementation Status: These docs describe the Attio API endpoints. For MCP tool usage, refer to universal tools documentation above.
API Overview - General Attio API concepts
Companies API - Company record endpoints ✅ Fully Implemented via Universal Tools
People API - Person record endpoints ✅ Fully Implemented via Universal Tools
Lists API - List management endpoints ✅ Fully Implemented
Notes API - Notes endpoints ✅ Basic Implementation
Tasks API - Task endpoints ✅ Implemented via Universal Tools
Advanced Topics
Batch Operations - Bulk operations ✅ Implemented with chunking
Advanced Filtering - Complex queries ✅ Implemented
Error Handling - Error patterns ✅ Enhanced error handling
Extending MCP - Customization guide
Deployment
🛠 Development
Setup Development Environment
Smithery CLI Development
For local development and testing with Smithery Playground:
See docs/deployment/smithery-cli-setup.md for detailed Smithery CLI development setup.
Testing
The project includes comprehensive testing at multiple levels with 100% E2E test pass rate:
🚀 E2E Test Framework (100% Pass Rate)
Our comprehensive E2E test framework validates all universal tools with real Attio API integration:
✅ Comprehensive Coverage:
Pagination Testing: Validates
offset
parameter across all universal toolsField Filtering: Tests
fields
parameter for selective data retrievalTasks Integration: Complete lifecycle testing for tasks resource type
Cross-Resource Validation: Ensures consistent behavior across companies, people, lists, tasks
Error Handling: Validates graceful error responses and edge cases
Performance Monitoring: Tracks execution times and API response sizes
🛠️ Enhanced Assertions (7 New Methods):
📊 Performance Benchmarks:
Search Operations: < 1000ms per API call
CRUD Operations: < 1500ms per operation
Batch Operations: < 3000ms for 10 records
Field Filtering: < 500ms additional overhead
Pagination: < 200ms additional per offset
Unit & Integration Tests
Test Environment Setup
For E2E and integration tests, you need:
Create in project root:
Verify API key format (must be exactly 64 characters)
Run tests to validate setup:
See the Testing Guide and E2E Troubleshooting Guide for detailed setup instructions.
Available Scripts
🤝 Contributing
We welcome contributions! Please see our Contributing Guidelines for details on:
Adding new tools and features
Improving documentation
Reporting bugs and requesting features
Testing and quality assurance
📈 What's Next?
This initial release provides a solid foundation for CRM automation.
🔗 Links
NPM Package: https://www.npmjs.com/package/attio-mcp
GitHub Repository: https://github.com/kesslerio/attio-mcp-server
Issues & Support: https://github.com/kesslerio/attio-mcp-server/issues
Releases: https://github.com/kesslerio/attio-mcp-server/releases
Attio Documentation: https://developers.attio.com/
📄 License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Original Work Attribution: This project is based on initial work by @hmk under BSD-3-Clause license, with substantial modifications and enhancements by @kesslerio. The original BSD license notice is preserved in the LICENSE file as required.
Ready to transform your CRM workflow? Install Attio MCP Server today and experience the future of CRM automation with AI!
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A Model Context Protocol server that enables AI assistants like Claude to interact directly with Attio CRM data, supporting operations for companies, people, lists, and tasks through natural language queries.
- 🎯 What is Attio MCP Server?
- 🚀 NEW: ChatGPT Developer Mode Integration
- ✨ Core Features & Implementation Status
- 🎯 Using Out-of-the-Box Prompts
- ⚠️ Known Limitations & Important Notes
- 🎯 Mastering Advanced Search Filters
- 🏆 Latest Updates - Critical Issues Resolved
- 🚀 Installation
- ⚡ Quick Start
- 🌟 Example Use Cases
- 🔐 Security & Privacy
- 📚 Documentation
- 🛠 Development
- 🤝 Contributing
- 📈 What's Next?
- 🔗 Links
- 📄 License
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol server that connects Claude and other MCP clients to Aider, enabling AI assistants to efficiently edit files, create new files, and interact with git repositories through natural language.Last updated -34The Unlicense
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.Last updated -12191MIT License
- AsecurityFlicenseAqualityA Model Context Protocol server that connects AI assistants like Claude to Notion workspaces, enabling them to view, search, create, and update Notion databases, pages, and content blocks.Last updated -122381
- AsecurityFlicenseAqualityA Model Context Protocol server that enables AI assistants like Claude to access and search Atlassian Confluence content, allowing integration with your organization's knowledge base.Last updated -751131