Attio
STDIOMCP server for Attio CRM integration, enabling AI assistants to access customer data.
MCP server for Attio CRM integration, enabling AI assistants to access customer data.
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"
v1.0.0 introduces full ChatGPT compatibility! ChatGPT Pro/Plus users can now access the entire Attio toolset through natural language via Smithery marketplace.
https://server.smithery.ai/@kesslerio/attio-mcp-server/mcp68% Tool Reduction: Consolidated 40+ resource-specific tools into 14 universal operations for consistent, powerful CRM management.
search-records and advanced-searchsearch-by-relationshipbatch-operationsget-detailed-infosearch-by-relationshipsearch-by-content and search-by-timeframeresource_type parameterIntelligent shortcuts that help Claude work faster with your CRM data:
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!
| Prompt | Description | Key Arguments | Example |
|---|---|---|---|
people_search.v1 | Find people by title, company, territory | query, limit, format | Find AE in fintech, SF |
company_search.v1 | Query companies by domain, segment, plan | query, limit, format | Find SaaS companies >100 employees |
deal_search.v1 | Filter deals by owner, stage, value, close date | query, limit, format | Find deals >$50k closing Q1 |
log_activity.v1 | Log calls/meetings/emails to records | target, type, summary, dry_run | Log call with Nina at Acme |
create_task.v1 | Create tasks with natural language due dates | title, content, due_date, dry_run | Create task: Follow up tomorrow |
advance_deal.v1 | Move deal to target stage with next action | deal, target_stage, create_task, dry_run | Advance deal to "Proposal Sent" |
add_to_list.v1 | Add records to a List by name or ID | records, list, dry_run | Add 5 companies to Q1 Outreach |
qualify_lead.v1 | Research lead with web + BANT/CHAMP scoring | target, framework, limit_web, dry_run | Qualify Acme Corp with BANT |
meeting_prep.v1 | 360° prep: notes, tasks, deals, agenda | target, format, verbosity | Prep for meeting with Acme CEO |
pipeline_health.v1 | Weekly snapshot: created/won/slipped + risks | owner, timeframe, segment | Pipeline health for @me last 30d |
# 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 executingPrompts include built-in token optimization:
MCP_DEV_META=true for token counts in responsesPROMPT_TELEMETRY_ENABLED=true for usage loggingMAX_PROMPT_TOKENS environment variableFor complete prompt documentation, see docs/prompts/v1-catalog.md.
/objects/tasks/attributes has limitations, handled with fallback patternsDISABLE_UNIVERSAL_TOOLS=true environment variable (deprecated)readOnlyHint, destructiveHint) so OpenAI Developer Mode can auto-approve reads and request confirmation for writes.ATTIO_MCP_TOOL_MODE in Smithery configuration for full access.search, fetch, aaa-health-check), explicitly configure ATTIO_MCP_TOOL_MODE: 'search' in Smithery dashboard when Developer Mode is unavailable.For detailed troubleshooting and solutions, see TROUBLESHOOTING.md and GitHub Issues.
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.
Every advanced search follows this proven pattern that's been battle-tested across thousands of CRM queries:
{ "resource_type": "companies", "filters": { "filters": [ { "attribute": { "slug": "field_name" }, "condition": "operator", "value": "search_value" } ] } }
🔍 Single Criteria Search
{ "resource_type": "companies", "filters": { "filters": [ { "attribute": { "slug": "name" }, "condition": "contains", "value": "Tech" } ] } }
🎯 Multi-Criteria Power Search (AND Logic)
{ "resource_type": "companies", "filters": { "filters": [ { "attribute": { "slug": "name" }, "condition": "contains", "value": "Tech" }, { "attribute": { "slug": "employee_count" }, "condition": "greater_than", "value": 50 }, { "attribute": { "slug": "industry" }, "condition": "equals", "value": "AI/Machine Learning" } ] } }
🚀 Flexible OR Logic
{ "resource_type": "companies", "filters": { "filters": [ { "attribute": { "slug": "name" }, "condition": "contains", "value": "Tech" }, { "attribute": { "slug": "name" }, "condition": "contains", "value": "AI" } ], "matchAny": true } }
| Operator | Perfect For | Example Use Case |
|---|---|---|
contains | Text searches | Finding companies with "Tech" in name |
equals | Exact matches | Specific industry classification |
starts_with | Prefix searches | Companies beginning with "Acme" |
ends_with | Suffix searches | Companies ending with "Inc" |
greater_than | Numerical analysis | Companies with 100+ employees |
less_than | Size filtering | Startups under 50 people |
is_empty | Data cleanup | Find records missing key information |
is_not_empty | Completeness checks | Records with populated fields |
🎯 Sales Teams - Use these field combinations:
name, industry, employee_count, website, locationfull_name, job_title, email, company📈 Marketing Teams - Focus on engagement fields:
last_interaction, email_status, campaign_responseindustry, company_size, location, engagement_score✅ Customer Success - Monitor health metrics:
renewal_date, support_tickets, usage_metricslast_contact, satisfaction_score, contract_value❌ Wrong (Flat object structure):
{ "filters": { "name": { "operator": "contains", "value": "Test" } } }
✅ Correct (Nested array structure):
{ "filters": { "filters": [ { "attribute": { "slug": "name" }, "condition": "contains", "value": "Test" } ] } }
Getting "Filters must include a 'filters' array property"?
filters arrayattribute, condition, and valueattribute must be an object with a slug property💬 Pro Tip: Start with simple single-filter searches, then build complexity once you're comfortable with the structure.
✅ 100% Integration Test Pass Rate Achieved - All critical API contract violations and build issues have been resolved:
/objects/tasks/attributes endpointSee TROUBLESHOOTING.md for detailed solutions to these resolved issues.
To install Attio CRM Integration Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @kesslerio/attio-mcp-server --client claude
# Global installation for CLI usage npm install -g attio-mcp-server # Or local installation for project integration npm install attio-mcp-server
curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/install.sh | bash
git clone https://github.com/kesslerio/attio-mcp-server.git cd attio-mcp-server npm install npm run build
export ATTIO_API_KEY="your_api_key_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="[email protected]" # Default owner email address (see below) export ATTIO_DEFAULT_CURRENCY="USD" # Default currency for deal values
# Test the MCP server attio-mcp-server --help # Discover your Attio workspace attributes attio-mcp-server 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
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.jsonis merged on top ofdefault.json, so only include overrides and additions. Don't duplicate mappings that already exist indefault.json.
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 topExample: If default.json has "Name": "name" and your user.json also has "Name": "name", that's wasted tokens. Only include fields that are:
{ "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" } } }
✅ 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:
"Find companies in our pipeline with lead score > 80"
Add to your Claude Desktop MCP configuration:
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.
# Example: export ATTIO_DEFAULT_DEAL_OWNER="[email protected]"
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.
{ "mcpServers": { "attio-mcp": { "command": "attio-mcp-server", "env": { "ATTIO_API_KEY": "your_api_key_here", "ATTIO_WORKSPACE_ID": "your_workspace_id_here", "ATTIO_DEFAULT_DEAL_STAGE": "Interested", "ATTIO_DEFAULT_DEAL_OWNER": "[email protected]", "ATTIO_DEFAULT_CURRENCY": "USD" } } } }
"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"
"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"
"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"
"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"
Comprehensive documentation is available in the docs directory:
⚠️ 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.
📋 Implementation Status: These docs describe the Attio API endpoints. For MCP tool usage, refer to universal tools documentation above.
git clone https://github.com/kesslerio/attio-mcp-server.git cd attio-mcp-server npm install npm run build npm run test:offline
For local development and testing with Smithery Playground:
npm run dev # Opens Smithery Playground with local server
See docs/deployment/smithery-cli-setup.md for detailed Smithery CLI development setup.
The project includes comprehensive testing at multiple levels with 100% E2E test pass rate:
Our comprehensive E2E test framework validates all universal tools with real Attio API integration:
# E2E Tests (requires ATTIO_API_KEY in .env file) npm run e2e # Run complete E2E test suite (51 tests, 100% pass rate) npm test -- test/e2e/suites/universal-tools.e2e.test.ts # Universal tools E2E tests # Set up E2E environment echo "ATTIO_API_KEY=your_api_key_here" > .env npm run e2e # Should show 51/51 tests passing
✅ Comprehensive Coverage:
offset parameter across all universal toolsfields parameter for selective data retrieval🛠️ Enhanced Assertions (7 New Methods):
// Available in test/e2e/utils/assertions.ts expectValidPagination(result, params); // Validates pagination behavior expectFieldFiltering(result, fields); // Validates field selection expectValidTasksIntegration(result); // Tasks-specific validation expectSpecificError(result, errorType); // Typed error validation expectOptimalPerformance(result, budget); // Performance validation expectValidUniversalToolParams(params); // Parameter validation expectValidBatchOperation(result, records); // Batch operation validation
📊 Performance Benchmarks:
# Unit Tests (no API required) npm test # Run all tests npm run test:offline # Run only offline tests (206 tests) npm run test:watch # Watch mode for development # Integration Tests (requires API key and test data) npm run test:integration # Run all integration tests (15 tests, 100% pass rate) npm run setup:test-data # Create test data in your workspace
For E2E and integration tests, you need:
.env file in project root:# Required for E2E/Integration tests ATTIO_API_KEY=your_64_character_api_key_here PORT=3000 LOG_LEVEL=debug NODE_ENV=development
npm run build && npm run test:integration
See the Testing Guide and E2E Troubleshooting Guide for detailed setup instructions.
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
We welcome contributions! Please see our Contributing Guidelines for details on:
This initial release provides a solid foundation for CRM automation.
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!
npm install -g attio-mcp-server