Attio MCP Server

Attio MCP 服务

面向 Attio 的完整模型上下文协议（MCP）服务，提供全面的 CRM 功能覆盖。此服务让 Claude 和 ChatGPT 等 AI 助手能够通过自然语言直接操作整个 Attio 工作区，无需回退到原始 API 调用，即可管理交易、任务、列表、人员、公司、记录和备注。

🎯 什么是 Attio MCP 服务？

借助 AI 驱动的自动化，变革您的 CRM 工作流。无需在多个屏幕间点击，只需用自然语言向 Claude 或 ChatGPT 提出请求，即可查找潜在客户、更新记录、管理销售渠道并分析数据。

🎉 v1.0.0 里程碑：全面覆盖 Attio CRM 功能，并完整集成 ChatGPT Developer Mode。

“查找所有员工人数超过 50 人且过去 30 天内未联系过的 AI 公司，并将它们添加到我们的 Q1 外联列表中”

🚀 ChatGPT Developer Mode 集成

⚠️ Smithery 暂时不可用：Smithery 已更改部署模式，现在需要外部托管。我们正在为 ChatGPT 用户开发 Cloudflare Worker 托管方案。在此期间，请使用 Tier 4（Cloudflare Worker）实现 ChatGPT/远程访问。

ChatGPT Pro/Plus 用户可以通过自托管的 Cloudflare Worker，以自然语言使用 Attio 工具集：

• 🔐 内置审批流程：MCP 安全注释会自动批准读取操作，并为写入操作请求审批
• 🌐 OAuth 集成：通过 Cloudflare Worker 部署自托管 OAuth
• 💬 自然语言 CRM：通过对话式 AI 管理整个 Attio 工作区
• 📖 设置指南：参阅 ChatGPT Developer Mode 文档和 Cloudflare Worker 指南

✨ 核心功能与实现状态

🎯 通用工具架构（19 个通用操作）

精简的工具集：将 40 多个针对特定资源的工具整合为通用操作，随后新增范围限定的高频写入工具，以便更安全地更新公司和交易。

• 高性能：速度提升 89.7%，内存减少 227KB（PR #483）
• 企业级质量：生产就绪评分达 97.15/100，且无任何破坏性变更
• 清晰的架构：通过模拟工厂模式，完全分离生产代码与测试代码
• 结构化结果：每个默认工具都声明了经过验证的输出架构；列表、成员、诊断和连接器输出请参阅结果契约，通用输出及文本退出选项请参阅前面的章节
• 范围限定的工具策略：仅当工作流使用频繁、通用写入可能修改错误的对象类别，且范围限定工具能省去模型的一项决策（而非仅仅重命名通用调用）时，才添加范围限定的默认工具

📊 功能实现状态

✅ 完整覆盖 CRM 所有功能

• 公司：搜索、创建、更新、删除、高级搜索、关系搜索
• 人员：搜索、创建、更新、删除、高级搜索、关系搜索
• 交易：完整的 CRUD 操作，支持智能字段映射和阶段验证
• 任务：创建、更新、删除、搜索，支持多个负责人
• 列表：完整的 CRUD 操作、筛选、高级筛选、条目管理
• 备注：适用于所有记录类型的创建和列表操作
• 记录：跨所有资源类型的通用 CRUD 操作
• 批量操作：创建、更新、删除，支持分块处理和错误处理
• 内容搜索：资源特定限制请参阅支持的输入矩阵
• 关系导航：公司↔人员↔交易的双向关系
• 高级筛选：支持智能字段映射的高级查询功能

📊 公司管理

• 通用搜索：使用 records_search 和 records_search_advanced 查找公司
• 范围限定的写入操作：使用 companies_create 和 companies_update 创建和更新公司
• 完整 CRUD：当没有范围限定的工具可用时，使用通用记录操作进行创建、读取、更新和删除
• 关系发现：使用 records_search_by_relationship 查找相关公司
• 批量操作：使用 records_batch 处理数百家公司
• 详细信息：使用 records_get_info 获取联系、业务和社交信息

👥 人员管理

• 通用联系人搜索：使用通用搜索工具按任意条件查找人员
• 关系跟踪：使用 records_search_by_relationship 将人员关联到公司
• 活动时间线：使用 records_get_interactions 获取交互元数据
• 高级筛选：使用通用筛选功能进行多属性搜索
• 批量操作：使用通用批量操作高效管理联系人

📋 列表和销售管道管理（6 个工具 + 8 个已弃用工具）

• 有效工具：4 个整合工具，支持自动模式检测（迁移指南）
  • list_entries_filter - 统一筛选，支持 4 种模式
  • list_entries_manage - 统一条目管理，支持 3 种模式
  • list_entries_list - 获取列表条目
  • records_get_list_memberships - 查找记录所属的列表
• 列表配置工具（专用工具；通用的 records_create/records_update 不接受 resource_type: "lists"）：
  • lists_create - 创建列表，并提供一流的访问控制：workspace_access（full-access | read-and-write | read-only | 私有列表使用 "null"）和 workspace_member_access（按成员授权）。省略这两个访问字段时，新列表默认对整个工作区开放完全访问权限；新列表必须至少有一位具备完全访问权限的授权对象。
  • lists_update_configuration - 更新名称、自定义字段和相同的访问控制。成员级授权可以提高高于工作区默认值的访问权限，但不能将权限降至 workspace_access 以下。
  • 错误会区分 plan_gating（工作区方案不支持所请求的访问配置）、permission_failure（令牌或工作区权限问题）和 unsupported_input（访问配置格式错误），并针对每种情况提供建议的后续步骤。
• 销售管道操作：推动交易进入不同的销售阶段
• 智能细分：创建和管理有针对性的联系人列表
• 高级筛选：支持 AND/OR 逻辑的复杂多条件筛选
• 条目管理：添加、移除和更新列表成员关系
• 交易跟踪：监控商机和收入管道
• 交易默认值：可配置默认阶段、负责人和货币，简化交易创建
• 范围限定的交易写入操作：使用 deals_create 和 deals_update 创建和更新交易

✅ 任务管理

• 通用任务操作：使用通用工具创建、更新和管理任务
• 关联记录：使用 resource_type 参数将任务与任意记录类型关联
• 进度跟踪：通过通用搜索和筛选监控完成情况
• 团队协作：通过一致的通用操作简化后续跟进

🔧 高级功能

• 批量处理：处理批量操作并跟踪错误
• 增强筛选：支持文本、数字、日期、布尔值和关系筛选，以及时间范围搜索（Issue #475）
• 数据导出：通过 JSON 序列化支持集成
• 实时更新：与 Attio 实时同步数据

🧠 Claude 技能

借助预构建技能增强 Claude 对 Attio 的了解，避免常见错误并掌握最佳实践。

快速入门（解决“字段名称错误”问题）：

npx attio-discover generate-skill --all --zip
# Import ZIP into Claude Desktop: Settings > Skills > Install Skill

完整的设置和使用指南请参阅技能文档。

💬 预构建提示词（10 个提示词）

智能快捷方式，帮助 Claude 更快地处理 CRM 数据：

• 搜索与查找（5 个）：people_search、company_search、deal_search、meeting_prep、pipeline_health
• 执行操作（4 个）：log_activity、create_task、advance_deal、add_to_list，并提供试运行安全机制
• 研究与资格判定（1 个）：qualify_lead，支持自动化网络研究以及 BANT/CHAMP 框架
• 节省令牌：每个提示词占用 300-700 个令牌，格式一致
• 易于发现：Claude 会自动为你的任务推荐相关提示词

详细文档和示例请参阅使用开箱即用的提示词。

🎯 使用开箱即用的提示词

新增：适用于常见销售工作流的 10 个预构建 MCP 提示词。无需设置——直接使用！

可用提示词

快速示例

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

通用参数

所有读取提示词均支持：

• format：table | json | ids（默认值：table）
• fields_preset：sales_short | full（默认值：sales_short）
• verbosity：brief | normal（默认值：brief）

所有写入提示词均支持：

• dry_run：true | false（默认值：false）- 预览变更但不执行

Token 感知功能

提示词内置了 Token 优化功能：

• 预算保护：提示词保持在 Token 限制范围内（people_search <500、qualify_lead <400）
• 开发元数据：设置 MCP_DEV_META=true，在响应中显示 Token 数量
• 遥测：设置 PROMPT_TELEMETRY_ENABLED=true，记录使用情况
• 可配置限制：使用环境变量 MAX_PROMPT_TOKENS 覆盖

完整的提示词文档请参阅 docs/prompts/v1-catalog.md。

⚠️ 已知限制与重要说明

当前限制

• 字段参数筛选：任务端点 /objects/tasks/attributes 存在限制，已通过备用模式处理
• 分页：支持的路径和有界任务结果请参阅集合续传约定

API 兼容性

• 通用工具：主要接口（19 个工具）——推荐用于所有新集成
• 旧版客户端：如需了解已移除的特定资源工具和受支持的先前默认别名，请遵循迁移指南
• Lists API：功能完整，支持完整的 CRUD 操作（与某些过时文档中的说法相反）

🤝 OpenAI MCP 兼容性

• 已就绪，可用于 Developer Mode：每个工具现在都会发布 MCP 安全注释（readOnlyHint、destructiveHint），以便 OpenAI Developer Mode 自动批准读取操作，并在写入操作前请求确认。
• 完整工具访问权限（默认）：默认公开完整目录；使用 MCP tools/list 查看当前清单。如需完整访问权限，请勿在 Smithery 配置中设置 ATTIO_MCP_TOOL_MODE。
• 仅搜索模式：若 Developer Mode 不可用，可在 Smithery 仪表板中明确配置 ATTIO_MCP_TOOL_MODE: 'search'，以限制为只读工具（search、fetch、aaa-health-check）。

了解工具的功能（无需试调用）

工具选择可通过静态元数据确定，因此客户端无需通过调用工具并查看错误来猜测。

• capabilities_get（仅限完整模式）会发布获准的功能清单：对于此服务公开的每个工具，清单都包含其输入和输出架构，以及操作信息——操作、资源类型、只读／破坏性／幂等标记、是否需要凭据、分页样式和上限，以及有关功能、边界、限制和恢复的指导。
• aaa-health-check 会返回其获准工具集的相同清单，并将内容限定在对应的操作部分，因此仅搜索客户端无需扩大允许列表，就能了解获准使用的工具。架构文档来自 capabilities_get 或 tools/list；健康状态载荷会在 capabilities.projection 中说明这一点。
• 两者都是静态的：均无需凭据，也不会调用 Attio；并且都不会将凭据回显到输出或日志中。

列出的工具表示已配置，而非已授权。每次调用仍会执行授权检查，因此清单中的条目仍可能被拒绝。

• 详细指南：有关环境变量、审批流程和验证提示，请参阅 docs/chatgpt-developer-mode.md。
• 用户文档：有关审批流程和设置说明的完整指南，请参阅 ChatGPT Developer Mode 文档。

性能注意事项

• 批量操作：通过分块、速率限制和错误恢复进行了优化
• 大型数据集：使用续页约定组合支持的集合分页内容
• 速率限制：内置保护机制，可防止触发 API 速率限制，并支持指数退避

如需详细的故障排查信息和解决方案，请参阅 TROUBLESHOOTING.md 和 GitHub Issues。

🎯 高级搜索筛选器

使用多条件 AND/OR 筛选构建强大的 CRM 查询。完整示例和运算符参考，请参阅高级搜索指南。

🚀 安装

⚠️ 重要：正确的软件包名称

npm 软件包名称为 attio-mcp（不是 attio-mcp-server）。 GitHub 仓库名为 attio-mcp-server，但 npm 软件包已于 2025 年 6 月更名为 attio-mcp。 安装 attio-mcp-server 会获得过时的 v0.0.2 版本，其中仅包含 4 个旧版工具。

客户端兼容性

选择安装方式：

• 大多数用户：使用 Tier 1（Shell 安装脚本）——只需一条命令，自动完成设置
• 高级用户：使用 Tier 2（手动配置）——完全掌控配置
• ChatGPT/Teams/Enterprise 用户：使用 Tier 3（Cloudflare Worker）——可自托管，支持多用户 OAuth

Tier 1：Shell 安装脚本

适合：偏好本地安装并希望自动配置的开发者。

只需一条命令，即可安装 attio-mcp 并自动配置客户端。

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

这些脚本将：

• 全局安装 attio-mcp npm 包（如有需要）
• 备份现有配置文件
• 提示输入 Attio API 密钥
• 为客户端配置 MCP 服务
• 显示后续步骤和重启说明

Tier 2：手动配置

适合：希望完全掌控配置或使用未受支持客户端的高级用户。

npm install -g attio-mcp

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

npm install -g attio-mcp

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

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

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

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

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（远程部署）

适合：需要集中式 OAuth、多用户访问、移动端访问或无需本地安装即可运行 MCP 的团队。

在 Cloudflare Workers 上部署自己的 Attio MCP 服务，并获得完整的 OAuth 2.1 支持。

移动端访问：使用远程 MCP 服务，即可通过以下方式使用 Attio 工具：

• ChatGPT 移动应用（iOS/Android）
• Claude 移动应用（iOS/Android）
• 任何设备上的任何浏览器

Cloudflare Worker 功能

快速部署

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

客户端配置

部署后，使用 Worker URL 配置客户端：

• Claude.ai：设置 → 连接器 → 添加 Worker URL
• ChatGPT：设置 → 连接器 → 开发者模式 → 添加 Worker URL

请参阅 Cloudflare Worker 部署指南，了解：

• 使用 Attio 完成 OAuth 2.1 设置
• 令牌加密配置
• 生产环境部署清单
• 故障排查指南

🆕 v1.4.0 新增内容

主要功能

• 🎯 工作区架构 Skill 生成器 (#983) - 根据 Attio 工作区架构自动生成 Claude Skills，确保字段名称和选项准确无误
• 🔍 选择字段转换器 (#1019) - 为选择/状态字段提供不区分大小写匹配、部分匹配和 UUID 直通支持
• 🛠️ Attio Skill 生成器元 Skill (#1020) - 用于自动生成工作区文档的元 Skill
• 📚 通用使用指南 Skill (#1018) - 手工编写的工作流模式和错误预防指南
• ⚙️ records_get_attribute_options 工具 (#975) - 获取选择/状态字段的有效选项，并提供增强的错误消息
• 📞 电话号码验证 (#951) - 内置电话号码验证支持
• ⏱️ 可配置的选项获取延迟 - 通过 --option-fetch-delay 标志控制速率限制

主要增强

• 🏷️ 符合 MCP 规范的工具命名 (#1039) - 所有工具现在均采用 snake_case、动词优先的命名方式（旧名称可通过别名继续使用，直到 v2.0.0）
• 🎨 自定义对象显示名称 (#1017) - 直接从 Attio API 获取显示名称
• 📖 拆分集成模式 (#1023) - 按使用场景提供渐进式发现模式
• 💡 增强属性错误消息 (#975) - 使用 Levenshtein 距离为拼写错误提供建议

关键修复

• 📝 保留备注内容中的换行符 (#1052)
• 👤 修复人员搜索结果中“未命名”的显示问题 (#1051)
• ✅ 选择字段持久化 (#1045)
• 🔗 记录引用自动转换 (#997)
• 📊 多选数组自动转换 (#992)
• 🛡️ 复杂属性验证 (#991)
• ⚠️ 修复字段持久化的误报警告 (#995)
• 📦 SDK 依赖项固定版本 (#1025)
• 💼 交易阶段/UTM 验证 (#1043)
• 📍 位置字段自动规范化 (#987)

内部改进

• 工具别名系统重构 (#1041) - 基于模式生成的类型安全常量
• CRUD 错误处理器采用策略模式 (#1001)
• 整合元数据获取逻辑 (#984)
• UniversalUpdateService 模块化 (#984)
• 选择转换类型重命名 (#1055) - 使用 select_title_to_array 以提高明确性

工具名称

服务端提供一个以资源为先的目录。search、fetch 和 aaa-health-check 保持不变。

旧版默认目录中的名称在 v2.x 中仍会调用同一工具。它们不会列在 tools/list 中，不会改变参数，并且设置 MCP_DISABLE_TOOL_ALIASES=true 后将无法使用。它们可能会在 v3.0.0 中移除。那些不属于该默认目录的名称（包括 search-records、create-record 和 records_search_batch）会立即失效。

完整映射请参阅 MIGRATION-GUIDE.md 和 src/constants/tool-names.ts。

⚡ 快速开始

前置条件

• Node.js（v18 或更高版本）
• Attio API 密钥（在此获取）或 OAuth 访问令牌
• Attio 工作区 ID

🔐 身份验证选项

服务器支持两种身份验证方式，二者都使用相同的 Bearer 令牌方案：

注意： 如果两者都已设置，ATTIO_API_KEY 优先。

OAuth 用户： 有关详细设置（包括 PKCE 流程和令牌刷新），请参阅 OAuth 身份验证指南。

1. 设置环境变量

# 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="[email protected]"     # Default owner email address (see below)
export ATTIO_DEFAULT_CURRENCY="USD"                    # Default currency for deal values

2. 测试安装

# Test the MCP server
attio-mcp --help

# Discover your Attio workspace attributes
attio-discover attributes

3. 🎯 至关重要：配置字段映射

MCP 服务使用字段映射文件，在自然语言和 Attio 的 API 字段名称之间进行转换。此配置对正常运行至关重要。

快速设置

# 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 - Attio 标准 CRM 字段（首先加载，请勿编辑）
• sample.json - 自定义字段模板示例（可从此文件复制，不会在运行时使用）
• user.json - 工作区专用覆盖项（合并至 default.json 之上）

💡 关键提示：user.json 会合并至 default.json 之上，因此只需包含覆盖项和新增项。请勿重复 default.json 中已有的映射。

配置合并方式

MCP 服务按以下顺序加载配置：

1. default.json - 包含所有标准 Attio 字段（名称、描述、团队等）
2. user.json - 自定义新增项/覆盖项会合并至其上

示例：如果 default.json 中有 "Name": "name"，而你的 user.json 中也有 "Name": "name"，就会浪费令牌。只需包含以下字段：

• 新的自定义字段（default.json 中没有的字段）
• 不同的映射（覆盖默认行为）

经过优化的 user.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"
    }
  }
}

✅ 良好：仅包含自定义字段/覆盖项
❌ 浪费：重复 default.json 中的标准字段

⚠️ 如果没有正确配置映射，MCP 服务可能无法正确处理你的自定义字段和列表。

下一步： 使用 Claude 测试并验证字段映射：

"Find companies in our pipeline with lead score > 80"

4. 配置 Claude Desktop

将以下内容添加到 Claude Desktop 的 MCP 配置中：

查找所需 ID

交易负责人邮箱（用于设置默认交易负责人）： ATTIO_DEFAULT_DEAL_OWNER 应设置为默认负责新交易的工作区成员的电子邮件地址。通常是你自己的邮箱地址或销售团队负责人的邮箱地址。

# Example:
export ATTIO_DEFAULT_DEAL_OWNER="[email protected]"

注意：创建交易时，系统会自动将电子邮件地址解析为工作区成员引用。

交易阶段： 交易阶段因工作区而异。请检查 Attio 工作区设置，或使用 discover-attributes 命令查找可用于交易的阶段。

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

🔐 安全与隐私

• 安全的 API 身份验证：采用行业标准的 API 密钥身份验证
• 不存储数据：直接转发 API 请求，不在本地保留数据
• 开源：基于 Apache 2.0 许可证，完全透明
• 可选的本地部署：部署在你自己的基础设施中
• npm 来源证明：使用 Sigstore 来源证明 发布 — 每个版本都通过加密方式关联到 GitHub Actions 构建和源代码提交

供应链验证

此软件包通过 npm 来源证明发布，建立了从源代码到已发布产物的可验证链路。验证某个版本：

# 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

为获得最高级别的供应链保护，请使用 pnpm v10+ 安装，它会强制执行以下规则：

• trustPolicy: no-downgrade — 阻止安装使用比先前版本更弱凭据发布的版本
• minimumReleaseAge — 新版本可安装前的冷却期

📚 文档

完整文档位于 docs 目录中：

通用工具（推荐）

⚠️ 注意：通用工具文档目前正在更新，以匹配最新实现。如需获取最准确的接口定义，请直接使用 API 或查看源代码。

• API 概览 - 高层 API 概念与模式
• 通用工具源代码 - 当前实现参考
• 工具架构 - 参数定义与验证

入门指南

• 安装与设置
• Claude Desktop 配置
• 故障排除指南

配置

• 警告过滤器配置 - 了解外观与语义不匹配、ESLint 预算和抑制策略
• 字段验证配置 - 字段持久性验证与校验设置
• 搜索评分配置 - 用于相关性评分、缓存和运算符验证的环境变量

API 参考

📋 实现状态：这些文档介绍 Attio API 端点。有关 MCP 工具的用法，请参阅上面的通用工具文档。

• API 概览 - Attio API 通用概念
• 公司 API - 公司记录端点 ✅ 已通过通用工具完整实现
• 人员 API - 人员记录端点 ✅ 已通过通用工具完整实现
• 列表 API - 列表管理端点 ✅ 已完整实现
• 备注 API - 备注端点 ✅ 已实现基本功能
• 任务 API - 任务端点 ✅ 已通过通用工具实现

高级主题

• 批量操作 - 批量操作 ✅ 已通过分块处理实现
• 高级筛选 - 复杂查询 ✅ 已实现
• 错误处理 - 错误模式 ✅ 已增强错误处理
• 扩展 MCP - 自定义指南

部署

• Docker 指南
• 安全最佳实践

🛠 开发

MCP SDK 兼容性

共享服务使用 @modelcontextprotocol/server 和 @modelcontextprotocol/core 的精确 2.3.1 版本。类型和协议错误来自 server 包；运行时 Zod 协议架构来自 core。可复用的 createServer(context?) 工厂会返回 SDK 的低级 Server。CLI 会将其连接到 @modelcontextprotocol/server/stdio 中的 StdioServerTransport。 这保留了旧版 initialize/serve 流程；升级包不会启用协议修订版 2026-07-28。

v2 客户端固定用于测试。v1 SDK 仍是开发依赖，用于较旧客户端的兼容性测试；现有 Worker 传输在迁移传输之前，仍保留可选的旧版对等依赖。两者都不是共享服务的第二个运行时所有者。领域结果架构、连接器内容以及不可重试的不确定写入结果均保持不变。无效的工具参数现在会收到 SDK 的 InvalidParams (-32602) 协议错误。

还原依赖项后，先构建，再运行 SDK 兼容性测试套件：

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

此测试套件会使用两代 SDK 客户端测试构建后的 CLI、公共库导出，以及 Worker 对本地 HTTP 测试夹具的已构建共享模块导入。还原示例锁定的开发依赖项后，也请运行：

bun run test:sdk:worker

单独的 Worker 检查使用其锁定的 Wrangler/Miniflare 工具链，以及示例中的 2024-12-01 兼容性日期和 nodejs_compat。它会构建临时打包文件，并在本地运行 workerd，测试缺失/无效会话的拒绝、经授权的旧版初始化/发现、输出架构，以及仅向拦截的上游发送一次的不确定删除操作。无需凭据，也无需访问在线 CRM。两项检查均不能证明现代协议服务或生产部署有效。请参阅官方 v2 迁移指南。

设置开发环境

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 开发

使用 Smithery Playground 进行本地开发和测试：

npm run dev  # Opens Smithery Playground with local server

详细的 Smithery CLI 开发环境设置，请参阅 docs/deployment/smithery-cli-setup.md。

测试

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)

对于端到端/集成测试，请创建包含你的 ATTIO_API_KEY 的 .env 文件。详细设置请参阅测试指南。

可用脚本

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

🤝 参与贡献

欢迎贡献！详情请参阅贡献指南，内容包括：

• 添加新工具和功能
• 改进文档
• 报告错误和请求功能
• 测试与质量保证

📈 接下来是什么？

此初始版本为 CRM 自动化提供了坚实的基础。

🔗 链接

• NPM 包：https://www.npmjs.com/package/attio-mcp
• GitHub 仓库：https://github.com/kesslerio/attio-mcp-server
• 问题与支持：https://github.com/kesslerio/attio-mcp-server/issues
• 发行版本：https://github.com/kesslerio/attio-mcp-server/releases
• Attio 文档：https://developers.attio.com/

📄 许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

原始作品归属：本项目基于 @hmk 在 BSD-3-Clause 许可下的初始作品，并由 @kesslerio 进行了大量修改和增强。按照要求，LICENSE 文件中保留了原始 BSD 许可证声明。

**准备好改变你的 CRM 工作流了吗？**立即安装 Attio MCP Server，借助 AI 体验 CRM 自动化的未来！

npm install -g attio-mcp