MCP Folk

🚀 Folk CRM MCP 服务器

Folk CRM MCP 服务器是一个 MCP（模型上下文协议）服务器，它提供对 Folk CRM 功能的访问，允许 AI 助手管理联系人、公司、笔记、提醒等。

🚀 快速开始

你可以通过以下两种方式将该服务器添加到 Claude Code 中：

从注册表添加（已发布版本）

# 配置你的 Folk API 密钥
mpak config set @nimblebraininc/folk api_key=your_api_key_here

# 添加到 Claude Code
claude mcp add folk -- mpak run @nimblebraininc/folk

本地开发环境添加

# 克隆并进入仓库
git clone https://github.com/NimbleBrainInc/mcp-folk.git
cd mcp-folk

# 安装依赖
uv sync

# 构建捆绑包
make pack

# 配置你的 API 密钥
mpak config set @nimblebraininc/folk api_key=your_api_key_here

# 添加到 Claude Code（使用绝对路径）
claude mcp add folk -- mpak run --local /path/to/mcp-folk/mcp-folk-0.1.0-darwin-arm64.mcpb

✨ 主要特性

• 智能搜索：以最少的令牌使用量按名称查找人员和公司。
• 两阶段查找：快速搜索返回 ID，然后根据需要获取完整详细信息。
• 联系人管理：创建、更新和删除人员与公司信息。
• 笔记与提醒：为联系人添加相关上下文信息。
• 交互记录：跟踪电子邮件、会议和电话记录。
• 内置技能资源：提供 skill://folk/usage 资源，教导大语言模型（LLMs）正确的工具路由、ID 格式规则和情景处理模式。

📦 安装指南

获取你的 Folk API 密钥

1. 登录到你的 Folk 工作区。
2. 转到 设置 > API。
3. 创建一个新的 API 密钥。
4. 复制密钥并使用 mpak config set 进行配置。

💻 使用示例

可用工具

搜索工具（优先使用）

详情工具（查找之后使用）

浏览工具

分组与过滤工具

操作工具

笔记与提醒工具

实用工具

常见用例

• 查找联系人
  • "我的 CRM 中有没有 Sarah Chen？"
  • "查找 Acme 公司的所有人员"
  • "John 的邮箱是什么？"
• 会议后添加联系人
  • "添加今天会议中的 Mike Johnson，他是 Stripe 的项目经理"
  • "为 lisa@example.com 创建一个联系人"
• 记录笔记
  • "给 Sarah 添加一条笔记：讨论了第二季度的路线图，她对企业计划感兴趣"
  • "我关于 Acme 交易的笔记有哪些？"
• 设置跟进提醒
  • "提醒我下周二跟进 John"
  • "设置一个提醒，两周后与 Sarah 联系"
• 记录交互信息
  • "记录我今天和 Mike 通了电话"
  • "记录我与 Acme 团队的会议"
• 浏览联系人
  • "显示我最近的联系人"
  • "列出我 CRM 中的所有公司"
• 查询分组和管道
  • "显示 '演示管理' 中状态为 '跟进 1' 的潜在客户"
  • "列出我的投资者组中的所有人员"
  • "查找我的客户组中的活跃客户"
  • "我在 Folk 中有哪些组？"

示例流程

用户：“我刚和 Alex Rivera 一起喝咖啡，她对我们的 API 感兴趣。提醒我下周给她发送文档。”

AI：find_person("Alex Rivera")
→ {"found": true, "matches": [{"id": "abc123", "name": "Alex Rivera", "email": "alex@techco.io"}]}

AI：add_note("abc123", "Had coffee - interested in API, wants to see docs")
→ {"id": "note456", "added": true}

AI：log_interaction("abc123", "meeting", "2024-01-15T10:00:00Z")
→ {"id": "int789", "logged": true}

AI：set_reminder("abc123", "Send API docs to Alex", "2024-01-22T09:00:00Z")
→ {"id": "rem012", "set": true}

AI：“完成！我已经添加了关于你们咖啡聊天的笔记，记录了会议，并设置了下周一给她发送 API 文档的提醒。”

🔧 技术细节

开发命令

# 安装开发依赖
uv sync --dev

# 运行测试
uv run pytest tests/ -v

# 格式化代码
uv run ruff format .

# 代码检查
uv run ruff check .

# 类型检查
uv run mypy src/

# 运行所有检查
make check

# 构建测试捆绑包
make pack

API 参考

此服务器使用 Folk REST API。关键端点信息如下：

• 基础 URL：https://api.folk.app/v1
• 认证方式：Bearer 令牌
• 有速率限制（详见 Folk 文档）

📄 许可证

本项目采用 MIT 许可证。