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"

🚀 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:

• 🔐 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

✨ Core Features & Implementation Status

🎯 Universal Tools Architecture (19 Universal Operations)

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
• Structured Results: Every default tool advertises a validated output schema; see the result contract for list, member, diagnostic, and connector outputs, and the preceding sections for universal outputs and prose opt-out
• 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

📊 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: See the supported-input matrix for resource-specific limits
• Relationship Navigation: Bidirectional company↔person↔deal relationships
• Advanced Filtering: Sophisticated query capabilities with intelligent field mapping

📊 Company Management

• Universal Search: Find companies with records_search and records_search_advanced
• Scoped Writes: Create and update companies with companies_create and companies_update
• Full CRUD: Create, read, update, and delete with universal record operations when a scoped tool is not available
• Relationship Discovery: Find companies through records_search_by_relationship
• Batch Operations: Process hundreds of companies with records_batch
• Detailed Information: Get contact, business, and social info with records_get_info

👥 People Management

• Universal Contact Search: Find people by any criteria using universal search tools
• Relationship Tracking: Link people to companies with records_search_by_relationship
• Activity Timeline: Retrieve interaction metadata with records_get_interactions
• Advanced Filtering: Multi-attribute search with universal filtering
• Bulk Operations: Efficiently manage contacts with universal batch operations

📋 Lists & Pipeline Management (6 Tools + 8 Deprecated)

• Active Tools: 4 consolidated tools with auto-mode detection (Migration Guide)
  • list_entries_filter - Unified filtering with 4 modes
  • list_entries_manage - Unified entry management with 3 modes
  • list_entries_list - Retrieve list entries
  • records_get_list_memberships - Find record's list memberships
• List Configuration Tools (dedicated; universal records_create/records_update reject resource_type: "lists"):
  • lists_create - 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.
  • lists_update_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.
• 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 deals_create and deals_update

✅ 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):

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.

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

# 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)
• 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 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.

⚠️ Known Limitations & Important Notes

Current Limitations

• Field Parameter Filtering: Tasks endpoint /objects/tasks/attributes has limitations, handled with fallback patterns
• Pagination: See the collection continuation contract for supported paths and bounded task results

API Compatibility

• Universal Tools: Primary interface (19 tools) - recommended for all new integrations
• Legacy clients: follow the migration guide for removed resource-specific tools and supported prior-default aliases
• 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): The complete catalogue is exposed by default; use MCP tools/list for the current inventory. 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.

Discovering What Tools Can Do (No Trial Calls)

Tool selection is answerable from static metadata, so a client does not have to guess by calling things and reading the errors.

• capabilities_get (full mode only) publishes the permitted capability manifest: for every tool this server advertises, its input and output schemas plus the operation facts — action, resource types, read-only/destructive/ idempotent flags, whether a credential is required, pagination style and cap, and guidance on capability, boundaries, limits, and recovery.
• aaa-health-check returns the same manifest for its permitted set, projected to its operation sections, so a search-only client can see what it is allowed to use without widening its allowlist. Schema documents come from capabilities_get or tools/list; the health payload says so in capabilities.projection.
• Both are static: neither needs a credential nor calls Attio, and neither echoes credentials into output or logs.

A listed tool is configured, not granted. Authorization is still enforced on every call, so a manifest entry can still come back denied.

• 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: Compose supported collection pages using the continuation contract
• Rate Limiting: Built-in protection against API rate limits with exponential backoff

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

🎯 Advanced Search Filters

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.

Client Compatibility

Client	Local Install (Tier 1-2)	Cloudflare Worker (Tier 3)
Claude Desktop	✅ Recommended	✅ Full support
Claude Web	N/A	✅ Full support
ChatGPT (Pro/Plus)	N/A	✅ Recommended
Cursor IDE	✅ Full support	✅ Full support
Claude Code (CLI)	✅ Recommended	Partial

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

---

Tier 1: Shell Installers

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

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

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

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

---

Tier 2: Manual Configuration

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

Step 1: Install attio-mcp

npm install -g attio-mcp

Step 2: Find your config file

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 3: Add configuration

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Step 4: Restart Claude Desktop completely (quit and reopen)

Step 1: Install attio-mcp

npm install -g attio-mcp

Step 2: Edit config file

Location: ~/.cursor/mcp.json

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Step 3: Restart Cursor

Option A: Using Claude CLI command (recommended)

echo '{"command":"attio-mcp","env":{"ATTIO_API_KEY":"your_key_here"}}' | claude mcp add-json attio-mcp --stdin -s user

Option B: Manual config edit

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "attio-mcp": {
      "command": "attio-mcp",
      "env": {
        "ATTIO_API_KEY": "your_api_key_here"
      }
    }
  }
}

For development or custom deployments:

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

Run directly:

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

---

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

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

---

🆕 What's New in v1.4.0

Major Features

• 🎯 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
• ⚙️ records_get_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

Major Enhancements

• 🏷️ 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

Critical Fixes

• 📝 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)

Internal Improvements

• 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

Tool names

The server advertises one resource-first catalog. search, fetch, and aaa-health-check are unchanged.

Prior default-catalog names still call the same tool through v2.x. They are not listed in tools/list, they do not change arguments, and MCP_DISABLE_TOOL_ALIASES=true makes them fail. They are removable in v3.0.0. Names that were never that default catalog, including search-records, create-record, and records_search_batch, fail immediately.

Prior name	Canonical name
search_records	records_search
create_record	records_create
get-lists	lists_list
manage-list-entry	list_entries_manage
get-workspace-member	workspace_members_get
smithery_debug_config	diagnostics_get

The full map is MIGRATION-GUIDE.md and src/constants/tool-names.ts.

⚡ Quick Start

Prerequisites

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

🔐 Authentication Options

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

Method	Environment Variable	Best For
API Key (recommended)	ATTIO_API_KEY	Long-term integrations, personal use
OAuth Access Token	ATTIO_ACCESS_TOKEN	OAuth integrations, third-party apps

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.

1. Set Environment Variables

# 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. Test the Installation

# 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

# 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

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:

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)

Optimized user.json Example

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

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.

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

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

🌟 Example Use Cases

For Sales Teams

"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

"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

"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

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

# 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
• Universal Tools Source - Current implementation reference
• Tool Schemas - Parameter definitions and validation

Getting Started

• Installation & Setup
• Claude Desktop Configuration
• Troubleshooting Guide

Configuration

• Warning Filter Configuration - Understanding cosmetic vs semantic mismatches, ESLint budgets, and suppression strategies
• Field Verification Configuration - Field persistence verification and validation settings
• Search Scoring Configuration - Environment variables for relevance scoring, caching, and operator validation

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

• Docker Guide
• Security Best Practices

🛠 Development

MCP SDK compatibility

The shared server uses exact 2.3.1 releases of @modelcontextprotocol/server and @modelcontextprotocol/core. Types and protocol errors come from the server package; runtime Zod protocol schemas come from core. The reusable createServer(context?) factory returns the SDK's low-level Server. The CLI connects it to StdioServerTransport from @modelcontextprotocol/server/stdio. This retains the legacy initialize/serve flow; upgrading packages does not activate protocol revision 2026-07-28.

The v2 client is pinned for tests. The v1 SDK remains a development dependency for older-client compatibility tests, and the existing Worker transport retains its optional legacy peer until its transport migration. Neither is a second runtime owner in the shared server. Domain result schemas, connector content, and nonretryable uncertain-write results are unchanged. Invalid tool parameters now receive the SDK's InvalidParams (-32602) protocol error.

After restoring dependencies, build before running the SDK compatibility suite:

bun run build
bun run test:single test/server/sdk-compatibility.test.ts

This suite exercises the built CLI with both SDK client generations, the public library export, and the Worker's built shared-module imports against local HTTP fixtures. After restoring the example's locked development dependencies, also run:

bun run test:sdk:worker

The separate Worker check uses its locked Wrangler/Miniflare toolchain and the example's 2024-12-01 compatibility date with nodejs_compat. It builds a temporary bundle and exercises workerd locally: missing/invalid session denial, authorized legacy initialization/discovery, output schemas, and an uncertain delete sent exactly once to an intercepted upstream. No credentials or live CRM access are needed. Neither check certifies modern protocol serving or a production deployment. See the official v2 migration guide.

Setup Development Environment

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

Smithery CLI Development

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.

Testing

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

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

🤝 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!

npm install -g attio-mcp