This Model Context Protocol (MCP) server provides AI-powered access to Attio CRM. It supports management of core CRM entities including contacts, companies, deals, tasks, notes, and workflows.
🛠️ Key Features
Attio CRM access via an MCP server
Tools for contacts, companies, deals, tasks, notes, and workflows
🚀 Use Cases
Retrieve and manage CRM records in Attio
Coordinate CRM-related work across contacts, companies, deals, tasks, notes, and workflows
⚡ Developer Benefits
Uses the MCP interface for Attio CRM operations
Package is available on npm (version badge shown in readme excerpt)
⚠️ Limitations
Provided source excerpt is truncated and does not include detailed setup, authentication, or tool specifications
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"
🚀 ChatGPT Developer Mode Integration
⚠️ 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:
Focused Tool Surface: Consolidated 40+ resource-specific tools into universal operations, then added scoped high-frequency write tools for safer company and deal updates.
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
Scoped Tool Policy: Add scoped default tools only when the workflow is frequent, a generic write can mutate the wrong object class, and the scoped tool removes a model decision instead of merely renaming a universal call
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
List Configuration Tools (dedicated; universal create_record/update_record reject resource_type: "lists"):
create-list - Create lists with first-class access controls: workspace_access (full-access | read-and-write | read-only | "null" for a private list) and workspace_member_access (per-member grants). Omitting both access fields defaults the new list to workspace-wide full access; new lists must keep at least one full-access grantee.
update-list-configuration - Update name, custom fields, and the same access controls. Member-level grants can raise access above the workspace default but never lower it below workspace_access.
Errors distinguish plan_gating (workspace plan does not support the requested access configuration) from permission_failure (token/workspace permissions) and unsupported_input (malformed access config), each with a suggested next step.
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
Scoped Deal Writes: Create and update deals with create_deal and update_deal
✅ Task Management
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
🔧 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
🧠 Claude Skills
Supercharge Claude's Attio knowledge with pre-built skills that prevent common errors and teach best practices.
Skill
Purpose
Setup
attio-mcp-usage
Error prevention + universal workflow patterns
Bundled - just use it
attio-workspace-schema
YOUR workspace's exact field names and options
npx attio-discover generate-skill --all --zip
attio-skill-generator
Create custom workflow skills (advanced)
Python + prompting
Quick Start (solves "wrong field name" errors):
bash
npx attio-discover generate-skill --all --zip
# Import ZIP into Claude Desktop: Settings > Skills > Install Skill
NEW: 10 pre-built MCP prompts for common Sales workflows. No setup required—just use them!
Available Prompts
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
Quick Examples
bash
# 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"
Universal Arguments
All read prompts support:
format: table | json | ids (default: table)
fields_preset: sales_short | full (default: sales_short)
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
API Compatibility
Universal Tools: Primary interface (19 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.
Full Tool Access (Default): All 41 tools are exposed by default (26 universal/OpenAI + 12 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.
Build powerful CRM queries with multi-criteria AND/OR filtering. See the Advanced Search Guide for complete examples and operator reference.
🚀 Installation
⚠️ 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.
git clone https://github.com/kesslerio/attio-mcp-server.git
cd attio-mcp-server
npm install
npm run build
Run directly:
bash
ATTIO_API_KEY=your_key node dist/index.js
NPM Global Install
bash
# Global installation for CLI usage
npm install -g attio-mcp
# Or local installation for project integration
npm install attio-mcp
Tier 3: Cloudflare Worker (Remote Deployment)
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
Cloudflare Worker Features
Feature
Cloudflare Worker
Setup complexity
Medium
OAuth built-in
✅
Mobile app access
✅
Multi-user access
✅
Custom domain
✅
Self-hosted
✅
Team deployments
✅ Full
Cost
Free tier
Quick Deploy
bash
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
Client Configuration
After deployment, configure your client with your Worker URL:
Claude.ai: Settings → Connectors → Add your Worker URL
# 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 configurationexport ATTIO_DEFAULT_DEAL_STAGE="Interested"# Default stage for new dealsexport ATTIO_DEFAULT_DEAL_OWNER="user@company.com"# Default owner email address (see below)export ATTIO_DEFAULT_CURRENCY="USD"# Default currency for deal values
2. Test the Installation
bash
# Test the MCP server
attio-mcp --help# Discover your Attio workspace attributes
attio-discover attributes
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
bash
# 1. Copy the sample configuration to create your user configcp 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
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 of default.json, so only include overrides and additions. Don't duplicate mappings that already exist in default.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
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"}}}
✅ 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:
code
"Find companies in our pipeline with lead score > 80"
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.
"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"
For Marketing Teams
code
"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"
For Customer Success
code
"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"
For Data Operations
code
"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"
🔐 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
npm Provenance: Published with Sigstore provenance — every release is cryptographically linked to the GitHub Actions build and source commit
Supply Chain Verification
This package is published with npm provenance, creating a verifiable chain from source code to published artifact. Verify a release:
sh
# 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
For maximum supply chain protection, install with pnpm v10+ which enforces:
trustPolicy: no-downgrade — blocks versions published with weaker credentials than prior versions
minimumReleaseAge — cooldown period before new versions can be installed
📚 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
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)
For E2E/integration tests, create .env with your ATTIO_API_KEY. See the Testing Guide for detailed setup.
Available Scripts
bash
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
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!
bash
npm install -g attio-mcp
Install
Configuration
Environment variables
ATTIO_API_KEYrequiredsecret
Your Attio API key (required for all tools except health-check)
ATTIO_WORKSPACE_ID
Optional Attio workspace ID for workspace-specific operations
