金大哥 - mcp-folk MCP 详情

article

README

🚀 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 密钥

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

💻 使用示例

可用工具

搜索工具（优先使用）

| 工具 | 用途 | |------|---------| | find_person(name) | 按名称查找人员，返回 {found, matches: [{id, name, email}]} | | find_company(name) | 按名称查找公司，返回 {found, matches: [{id, name, industry}]} |

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

| 工具 | 用途 | |------|---------| | get_person_details(person_id) | 获取人员的完整信息，包括所有字段 | | get_company_details(company_id) | 获取公司的完整信息，包括所有字段 |

浏览工具

| 工具 | 用途 | |------|---------| | browse_people(page, per_page) | 获取所有人员的分页列表 | | browse_companies(page, per_page) | 获取所有公司的分页列表 |

分组与过滤工具

| 工具 | 用途 | |------|---------| | list_groups() | 列出工作区中的所有组 | | find_people_in_group(group_name, status) | 查找某个组中的人员，可根据状态进行过滤 | | find_companies_in_group(group_name, status) | 查找某个组中的公司，可根据状态进行过滤 |

操作工具

| 工具 | 用途 | |------|---------| | add_person(first_name, ...) | 创建新的人员信息 | | add_company(name, ...) | 创建新的公司信息 | | update_person(person_id, ...) | 更新人员的字段信息 | | update_company(company_id, ...) | 更新公司的字段信息 | | delete_person(person_id) | 删除人员信息 | | delete_company(company_id) | 删除公司信息 |

笔记与提醒工具

| 工具 | 用途 | |------|---------| | add_note(person_id, content) | 为人员添加笔记 | | get_notes(person_id) | 获取人员的笔记 | | set_reminder(person_id, reminder, when) | 设置提醒 | | log_interaction(person_id, type, when) | 记录交互信息 |

实用工具

| 工具 | 用途 | |------|---------| | whoami() | 获取当前认证用户信息 |

常见用例

查找联系人
- "我的 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 许可证。

mcp-folk