Claude Desktop Manual Setup

\n\n#### Step 1: Install attio-mcp\n\n```bash\nnpm install -g attio-mcp\n```\n\n#### Step 2: Find your config file\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n#### Step 3: Add configuration\n\n```json\n{\n \"mcpServers\": {\n \"attio-mcp\": {\n \"command\": \"attio-mcp\",\n \"env\": {\n \"ATTIO_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\n#### Step 4: Restart Claude Desktop completely (quit and reopen)\n\n

\n\n

Cursor IDE Manual Setup

\n\n#### Step 1: Install attio-mcp\n\n```bash\nnpm install -g attio-mcp\n```\n\n#### Step 2: Edit config file\n\nLocation: `~/.cursor/mcp.json`\n\n```json\n{\n \"mcpServers\": {\n \"attio-mcp\": {\n \"command\": \"attio-mcp\",\n \"env\": {\n \"ATTIO_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\n#### Step 3: Restart Cursor\n\n

\n\n

Claude Code (CLI) Manual Setup

\n\n#### Option A: Using Claude CLI command (recommended)\n\n```bash\necho '{\"command\":\"attio-mcp\",\"env\":{\"ATTIO_API_KEY\":\"your_key_here\"}}' | claude mcp add-json attio-mcp --stdin -s user\n```\n\n#### Option B: Manual config edit\n\nEdit `~/.claude/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"attio-mcp\": {\n \"command\": \"attio-mcp\",\n \"env\": {\n \"ATTIO_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\n

\n\n

Building from Source

\n\nFor development or custom deployments:\n\n```bash\ngit clone https://github.com/kesslerio/attio-mcp-server.git\ncd attio-mcp-server\nnpm install\nnpm run build\n```\n\nRun directly:\n\n```bash\nATTIO_API_KEY=your_key node dist/index.js\n```\n\n

\n\n

NPM Global Install

\n\n```bash\n# Global installation for CLI usage\nnpm install -g attio-mcp\n\n# Or local installation for project integration\nnpm install attio-mcp\n```\n\n

\n\n---\n\n### Tier 3: Cloudflare Worker (Remote Deployment)\n\n> **Best for**: Teams needing centralized OAuth, multi-user access, mobile access, or running MCP without local installation.\n\nDeploy your own Attio MCP server on Cloudflare Workers with full OAuth 2.1 support.\n\n**Mobile Access**: With a remote MCP server, you can use Attio tools from:\n\n- ChatGPT mobile app (iOS/Android)\n- Claude mobile app (iOS/Android)\n- Any browser on any device\n\n#### Cloudflare Worker Features\n\n| Feature | Cloudflare Worker |\n| ----------------- | ----------------- |\n| Setup complexity | Medium |\n| OAuth built-in | ✅ |\n| Mobile app access | ✅ |\n| Multi-user access | ✅ |\n| Custom domain | ✅ |\n| Self-hosted | ✅ |\n| Team deployments | ✅ Full |\n| Cost | Free tier |\n\n#### Quick Deploy\n\n```bash\ncd examples/cloudflare-mcp-server\nnpm install\nwrangler kv:namespace create \"TOKEN_STORE\"\n# Update wrangler.toml with the KV namespace ID\nwrangler secret put ATTIO_CLIENT_ID\nwrangler secret put ATTIO_CLIENT_SECRET\nwrangler secret put TOKEN_ENCRYPTION_KEY\nwrangler deploy\n```\n\n#### Client Configuration\n\nAfter deployment, configure your client with your Worker URL:\n\n- **Claude.ai**: Settings → Connectors → Add your Worker URL\n- **ChatGPT**: Settings → Connectors → Developer Mode → Add Worker URL\n\nSee [Cloudflare Worker Deployment Guide](https://github.com/kesslerio/attio-mcp-server/blob/main/examples/cloudflare-mcp-server/README.md) for:\n\n- Complete OAuth 2.1 setup with Attio\n- Token encryption configuration\n- Production deployment checklist\n- Troubleshooting guide\n\n---\n\n## 🆕 What's New in v1.4.0\n\n### Major Features\n\n- **🎯 Workspace Schema Skill Generator** (#983) - Auto-generate Claude Skills from your Attio workspace schema for error-free field names and options\n- **🔍 Select-field Transformer** (#1019) - Case-insensitive matching, partial matching, and UUID pass-through for select/status fields\n- **🛠️ Attio Skill Generator Meta-skill** (#1020) - Meta-skill for automatic workspace documentation\n- **📚 Universal Usage Guide Skill** (#1018) - Hand-crafted workflow patterns and error prevention\n- **⚙️ `get_record_attribute_options` tool** (#975) - Get valid options for select/status fields with enhanced error messages\n- **📞 Phone validation** (#951) - Built-in phone number validation support\n- **⏱️ Configurable option fetch delay** - Rate limiting control via `--option-fetch-delay` flag\n\n### Major Enhancements\n\n- **🏷️ MCP-compliant tool naming** (#1039) - All tools now use `snake_case`, verb-first naming (old names work via aliases until v2.0.0)\n- **🎨 Custom object display names** (#1017) - Fetch display names directly from Attio API\n- **📖 Split integration patterns** (#1023) - Progressive discovery patterns by use case\n- **💡 Enhanced attribute error messages** (#975) - Levenshtein distance suggestions for typos\n\n### Critical Fixes\n\n- 📝 Note content line breaks preserved (#1052)\n- 👤 People search \"Unnamed\" display fixed (#1051)\n- ✅ Select field persistence (#1045)\n- 🔗 Record-reference auto-transformation (#997)\n- 📊 Multi-select array auto-transformation (#992)\n- 🛡️ Complex attribute validation (#991)\n- ⚠️ Field persistence false warnings (#995)\n- 📦 SDK dependency pinning (#1025)\n- 💼 Deal stage/UTM validation (#1043)\n- 📍 Location field auto-normalization (#987)\n\n### Internal Improvements\n\n- Tool alias system refactoring (#1041) - Type-safe constants with pattern-based generation\n- Strategy Pattern for CRUD error handlers (#1001)\n- Consolidated metadata fetching (#984)\n- UniversalUpdateService modularization (#984)\n- Select transformation type rename (#1055) - `select_title_to_array` for clarity\n\n## 🔄 Migration Guide\n\n**Upgrading from v1.3.x or earlier?** Tool names have changed to follow MCP naming conventions.\n\n**Old names still work** via backward-compatible aliases, but will be removed in **v2.0.0 (Q1 2026)**.\n\n### Tool Name Changes\n\n| Old Name (Deprecated) | New Name (MCP-compliant) | Notes |\n| -------------------------------- | -------------------------------- | ------------------ |\n| `records_search` | `search_records` | Verb-first pattern |\n| `records_get_details` | `get_record_details` | Verb-first pattern |\n| `records_get_attributes` | `get_record_attributes` | Verb-first pattern |\n| `records_discover_attributes` | `discover_record_attributes` | Verb-first pattern |\n| `records_search_advanced` | `search_records_advanced` | Verb-first pattern |\n| `records_search_by_relationship` | `search_records_by_relationship` | Verb-first pattern |\n| `records_search_by_content` | `search_records_by_content` | Verb-first pattern |\n| `records_search_by_timeframe` | `search_records_by_timeframe` | Verb-first pattern |\n| `records_batch` | `batch_records` | Verb-first pattern |\n| `search-records` | `search_records` | snake_case format |\n| `get-record-details` | `get_record_details` | snake_case format |\n| `create-record` | `create_record` | snake_case format |\n| `update-record` | `update_record` | snake_case format |\n| `delete-record` | `delete_record` | snake_case format |\n| `create-note` | `create_note` | snake_case format |\n| `list-notes` | `list_notes` | snake_case format |\n| `smithery-debug-config` | `smithery_debug_config` | snake_case format |\n\n**Action Required:** Update your integrations to use new tool names before Q1 2026. See [MIGRATION-GUIDE.md](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/MIGRATION-GUIDE.md) for the complete migration table.\n\n---\n\n## ⚡ Quick Start\n\n### Prerequisites\n\n- Node.js (v18 or higher)\n- Attio API Key ([Get one here](https://app.attio.com/settings/api)) **or** OAuth access token\n- Attio Workspace ID\n\n### 🔐 Authentication Options\n\nThe server supports two authentication methods—both use the same Bearer token scheme:\n\n| Method | Environment Variable | Best For |\n| ------------------------- | -------------------- | ------------------------------------ |\n| **API Key** (recommended) | `ATTIO_API_KEY` | Long-term integrations, personal use |\n| **OAuth Access Token** | `ATTIO_ACCESS_TOKEN` | OAuth integrations, third-party apps |\n\n> **Note:** If both are set, `ATTIO_API_KEY` takes precedence.\n>\n> **OAuth Users:** For detailed setup including PKCE flow and token refresh, see [OAuth Authentication Guide](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/guides/oauth-authentication.md).\n\n### 1. Set Environment Variables\n\n```bash\n# Option 1: API Key (recommended for most users)\nexport ATTIO_API_KEY=\"your_api_key_here\"\n\n# Option 2: OAuth Access Token (for OAuth integrations)\n# export ATTIO_ACCESS_TOKEN=\"your_oauth_access_token_here\"\n\nexport ATTIO_WORKSPACE_ID=\"your_workspace_id_here\"\n\n# Optional: Deal defaults configuration\nexport ATTIO_DEFAULT_DEAL_STAGE=\"Interested\" # Default stage for new deals\nexport ATTIO_DEFAULT_DEAL_OWNER=\"user@company.com\" # Default owner email address (see below)\nexport ATTIO_DEFAULT_CURRENCY=\"USD\" # Default currency for deal values\n```\n\n### 2. Test the Installation\n\n```bash\n# Test the MCP server\nattio-mcp --help\n\n# Discover your Attio workspace attributes\nattio-discover attributes\n```\n\n### 3. 🎯 **CRITICAL: Configure Field Mappings**\n\nThe MCP server uses **field mapping files** to translate between natural language and Attio's API field names. **This configuration is essential for proper operation.**\n\n#### **Quick Setup**\n\n```bash\n# 1. Copy the sample configuration to create your user config\ncp configs/runtime/mappings/sample.json configs/runtime/mappings/user.json\n\n# 2. Edit user.json to match your workspace's custom fields\n# Focus on the \"objects.companies\" and \"objects.people\" sections\n```\n\n#### **Configuration Files** (in `configs/runtime/mappings/`)\n\n- **`default.json`** - Standard Attio CRM fields (loaded first, don't edit)\n- **`sample.json`** - Examples with custom field templates (copy from this, not used at runtime)\n- **`user.json`** - **YOUR workspace-specific overrides** (merged on top of default.json)\n\n> 💡 **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`.\n\n#### **How Configuration Merging Works**\n\nThe MCP server loads configuration in this order:\n\n1. **`default.json`** - Contains all standard Attio fields (Name, Description, Team, etc.)\n2. **`user.json`** - Your custom additions/overrides are **merged on top**\n\n**Example**: If `default.json` has `\"Name\": \"name\"` and your `user.json` also has `\"Name\": \"name\"`, that's wasted tokens. Only include fields that are:\n\n- **New custom fields** (not in default.json)\n- **Different mappings** (overriding default behavior)\n\n#### **Optimized user.json Example**\n\n```json\n{\n \"mappings\": {\n \"attributes\": {\n \"objects\": {\n \"companies\": {\n \"// Only your custom fields - defaults are inherited\": \"\",\n \"Lead Score\": \"lead_score\",\n \"B2B Segment\": \"b2b_segment\",\n \"Industry Vertical\": \"custom_industry_field\"\n }\n }\n },\n \"lists\": {\n \"// Only your specific lists\": \"\",\n \"Sales Pipeline\": \"your-pipeline-list-id\"\n }\n }\n}\n```\n\n**✅ Good**: Only custom/override fields \n**❌ Wasteful**: Duplicating standard fields from default.json\n\n> ⚠️ **Without proper mapping configuration, the MCP server may not work correctly with your custom fields and lists.**\n\n**Next:** Verify your field mappings work by testing with Claude:\n\n```\n\"Find companies in our pipeline with lead score > 80\"\n```\n\n### 4. Configure Claude Desktop\n\nAdd to your Claude Desktop MCP configuration:\n\n#### Finding Required IDs\n\n**Deal Owner Email** (for deal owner defaults):\nThe `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.\n\n```bash\n# Example:\nexport ATTIO_DEFAULT_DEAL_OWNER=\"john.smith@company.com\"\n```\n\n**Note**: The system will automatically resolve email addresses to workspace member references when creating deals.\n\n**Deal Stages**:\nDeal stages are specific to your workspace. Check your Attio workspace settings or use the `discover-attributes` command to find available stages for deals.\n\n```json\n{\n \"mcpServers\": {\n \"attio-mcp\": {\n \"command\": \"attio-mcp\",\n \"env\": {\n \"ATTIO_API_KEY\": \"your_api_key_here\",\n \"ATTIO_WORKSPACE_ID\": \"your_workspace_id_here\",\n \"ATTIO_DEFAULT_DEAL_STAGE\": \"Interested\",\n \"ATTIO_DEFAULT_DEAL_OWNER\": \"user@company.com\",\n \"ATTIO_DEFAULT_CURRENCY\": \"USD\"\n }\n }\n }\n}\n```\n\n## 🌟 Example Use Cases\n\n### **For Sales Teams**\n\n```\n\"Find all companies in the AI space with 50+ employees that we haven't contacted in 30 days\"\n\"Show me all prospects added yesterday\"\n\"Find companies created in the last 7 days with revenue over $10M\"\n\"Create a task to follow up with Microsoft about the enterprise deal\"\n\"Add John Smith from Google to our Q1 prospect list\"\n```\n\n### **For Marketing Teams**\n\n```\n\"Create a list of all SaaS companies who opened our last 3 emails but haven't responded\"\n\"Show me engagement metrics for our outbound campaign this month\"\n\"Add all attendees from the conference to our nurture sequence\"\n```\n\n### **For Customer Success**\n\n```\n\"Show me all enterprise customers with upcoming renewal dates in Q1\"\n\"Create tasks for check-ins with accounts that haven't been contacted in 60 days\"\n\"Find all customers who mentioned pricing concerns in recent notes\"\n```\n\n### **For Data Operations**\n\n```\n\"Update all companies with missing industry data based on their domains\"\n\"Export all contacts added this quarter to CSV\"\n\"Merge duplicate company records for Acme Corporation\"\n```\n\n## 🔐 Security & Privacy\n\n- **Secure API Authentication**: Industry-standard API key authentication\n- **No Data Storage**: Direct API passthrough with no local data retention\n- **Open Source**: Full transparency with Apache 2.0 license\n- **Optional On-Premises**: Deploy in your own infrastructure\n- **npm Provenance**: Published with [Sigstore provenance](https://docs.npmjs.com/generating-provenance-statements) — every release is cryptographically linked to the GitHub Actions build and source commit\n\n### Supply Chain Verification\n\nThis package is published with npm provenance, creating a verifiable chain from source code to published artifact. Verify a release:\n\n```sh\n# Check provenance attestation on any published version\nnpm view attio-mcp --json | jq .attestations\n\n# With pnpm (v10+), enforce trust policy at install time\n# pnpm trustPolicy: no-downgrade blocks packages published with weaker credentials\n```\n\nFor maximum supply chain protection, install with [pnpm v10+](https://pnpm.io) which enforces:\n\n- **`trustPolicy: no-downgrade`** — blocks versions published with weaker credentials than prior versions\n- **`minimumReleaseAge`** — cooldown period before new versions can be installed\n\n## 📚 Documentation\n\nComprehensive documentation is available in the [docs directory](https://github.com/kesslerio/attio-mcp-server/blob/main/docs):\n\n### **Universal Tools (Recommended)**\n\n⚠️ **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.\n\n- [API Overview](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/api-overview.md) - High-level API concepts and patterns\n- [Universal Tools Source](https://github.com/kesslerio/attio-mcp-server/blob/main/src/handlers/tool-configs/universal/) - Current implementation reference\n- [Tool Schemas](https://github.com/kesslerio/attio-mcp-server/blob/main/src/handlers/tool-configs/universal/schemas.ts) - Parameter definitions and validation\n\n### **Getting Started**\n\n- [Installation & Setup](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/getting-started.md)\n- [Claude Desktop Configuration](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/claude-desktop-config.md)\n- [Troubleshooting Guide](https://github.com/kesslerio/attio-mcp-server/blob/main/TROUBLESHOOTING.md)\n\n### **Configuration**\n\n- [Warning Filter Configuration](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/configuration/warning-filters.md) - Understanding cosmetic vs semantic mismatches, ESLint budgets, and suppression strategies\n- [Field Verification Configuration](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/configuration/field-verification.md) - Field persistence verification and validation settings\n- [Search Scoring Configuration](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/configuration/search-scoring.md) - Environment variables for relevance scoring, caching, and operator validation\n\n### **API Reference**\n\n📋 **Implementation Status**: These docs describe the Attio API endpoints. For MCP tool usage, refer to universal tools documentation above.\n\n- [API Overview](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/api-overview.md) - General Attio API concepts\n- [Companies API](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/companies-api.md) - Company record endpoints ✅ Fully Implemented via Universal Tools\n- [People API](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/people-api.md) - Person record endpoints ✅ Fully Implemented via Universal Tools\n- [Lists API](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/lists-api.md) - List management endpoints ✅ Fully Implemented\n- [Notes API](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/notes-api.md) - Notes endpoints ✅ Basic Implementation\n- [Tasks API](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/tasks-api.md) - Task endpoints ✅ Implemented via Universal Tools\n\n### **Advanced Topics**\n\n- [Batch Operations](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/batch-operations.md) - Bulk operations ✅ Implemented with chunking\n- [Advanced Filtering](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/advanced-filtering.md) - Complex queries ✅ Implemented\n- [Error Handling](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/error-handling.md) - Error patterns ✅ Enhanced error handling\n- [Extending MCP](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/api/extending-mcp.md) - Customization guide\n\n### **Deployment**\n\n- [Docker Guide](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/docker/docker-guide.md)\n- [Security Best Practices](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/docker/security-guide.md)\n\n## 🛠 Development\n\n### **Setup Development Environment**\n\n```bash\ngit clone https://github.com/kesslerio/attio-mcp-server.git\ncd attio-mcp-server\nnpm install\nnpm run build\nnpm run test:offline\n```\n\n### **Smithery CLI Development**\n\nFor local development and testing with Smithery Playground:\n\n```bash\nnpm run dev # Opens Smithery Playground with local server\n```\n\nSee [docs/deployment/smithery-cli-setup.md](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/deployment/smithery-cli-setup.md) for detailed Smithery CLI development setup.\n\n### **Testing**\n\n```bash\nnpm test # Run all tests\nnpm run test:offline # Run only offline tests (no API required)\nnpm run test:integration # Integration tests (requires ATTIO_API_KEY)\nnpm run e2e # E2E tests (requires ATTIO_API_KEY)\n```\n\nFor E2E/integration tests, create `.env` with your `ATTIO_API_KEY`. See the [Testing Guide](https://github.com/kesslerio/attio-mcp-server/blob/main/docs/testing.md) for detailed setup.\n\n### **Available Scripts**\n\n```bash\nnpm run build # Build TypeScript\nnpm run test # Run all tests\nnpm run test:offline # Run tests without API calls\nnpm run analyze:token-footprint # Generate baseline MCP token footprint report\nnpm run lint # Check code style\nnpm run check # Full quality check\nnpm run setup:test-data # Create test data for integration tests\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](https://github.com/kesslerio/attio-mcp-server/blob/main/CONTRIB.md) for details on:\n\n- Adding new tools and features\n- Improving documentation\n- Reporting bugs and requesting features\n- Testing and quality assurance\n\n## 📈 What's Next?\n\nThis initial release provides a solid foundation for CRM automation.\n\n## 🔗 Links\n\n- **NPM Package**: https://www.npmjs.com/package/attio-mcp\n- **GitHub Repository**: https://github.com/kesslerio/attio-mcp-server\n- **Issues & Support**: https://github.com/kesslerio/attio-mcp-server/issues\n- **Releases**: https://github.com/kesslerio/attio-mcp-server/releases\n- **Attio Documentation**: https://developers.attio.com/\n\n## 📄 License\n\nThis project is licensed under the **Apache License 2.0** - see the [LICENSE](https://github.com/kesslerio/attio-mcp-server/blob/main/LICENSE) file for details.\n\n**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.\n\n---\n\n**Ready to transform your CRM workflow?** Install Attio MCP Server today and experience the future of CRM automation with AI!\n\n```bash\nnpm install -g attio-mcp\n```\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"categoryDisplayName","Productivity","upstream",{"_95":96,"_97":98,"_99":100,"_101":102,"_103":-5},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_93":80,"_94":80},"ratingAvg","reviewCount","topics",[],"license","NOASSERTION","language","TypeScript","registryName","ai.smithery/kesslerio-attio-mcp-server","homepage","ENV",{"_106":107,"_108":109,"_110":111},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]

attio mcp server