attio-mcp-server MCP工具

Prerequisites

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

Import ZIP into Claude Desktop: Settings > Skills > Install Skill

```

See Skills Documentation for complete setup and usage guides.

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

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

---

Global installation for CLI usage

npm install -g attio-mcp

Or local installation for project integration

npm install attio-mcp ```

</details>

---

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

Quick Deploy

```bash cd examples/cloudflare-mcp-server npm install wrangler kv:namespace create "TOKEN_STORE"

2. Test the Installation

```bash

With pnpm (v10+), enforce trust policy at install time

**Getting Started**

• Installation & Setup
• Claude Desktop Configuration
• Troubleshooting Guide

**Deployment**

• Docker Guide
• Security Best Practices

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

Quick Examples

```bash

🔄 Migration Guide

Upgrading from v1.3.x or earlier? Tool names have changed to follow MCP naming conventions.

Old names still work via backward-compatible aliases, but will be removed in v2.0.0 (Q1 2026).

⚡ Quick Start

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.

🌟 Example Use Cases

Tier 2: Manual Configuration

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

<details> <summary><strong>Claude Desktop Manual Setup</strong></summary>

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)

</details>

<details> <summary><strong>Cursor IDE Manual Setup</strong></summary>

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

</details>

<details> <summary><strong>Claude Code (CLI) Manual Setup</strong></summary>

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

</details>

<details> <summary><strong>Building from Source</strong></summary>

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

</details>

<details> <summary><strong>NPM Global Install</strong></summary>

```bash

🔐 Authentication Options

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

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

```bash

Option 1: API Key (recommended for most users)

export ATTIO_API_KEY="your_api_key_here"

Option 2: OAuth Access Token (for OAuth integrations)

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

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 config

cp configs/runtime/mappings/sample.json configs/runtime/mappings/user.json

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.

```bash

**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 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)

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

**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.

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

📋 **Lists & Pipeline Management** (4 Tools + 8 Deprecated)

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

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