Monica CRM MCP服务器
一个模型上下文协议（MCP）服务器，允许Claude Desktop等助手对任何Monica CRM实例进行读写操作。它为Monica的REST API提供了一些有助于助手的工具和资源，因此您可以在不离开聊天室的情况下搜索联系人、检查时间表、捕获笔记并掌握任务。
特性
- 联系人搜索和摘要 –按姓名/电子邮件查找人员，并返回带有自定义字段的规范化详细信息。
- 联系人管理 –在不离开助手的情况下创建、更新或删除联系人。
- 联系方式管理 –通过一个工具查看联系人摘要、更新个人资料详细信息和管理通信字段/地址。
- 活动跟踪 –记录会议/外出活动，并查看最近的共享历史记录。
- 自动ID解析 –执行工具时，按名称查找性别、国家、联系人字段类型、活动类型和关系类型。
- 元数据浏览器 –当您需要原始ID时，可以从一个综合工具中检查Monica目录（性别、国家、活动类型等）。
- 保持正轨行动 –创建或更新任务和提醒，而无需同时使用多个工具。
- 财务跟踪 –通过一个共享工具记录莫妮卡的礼物和债务。
- 关系管理 –检查现有链接或连接两个正确类型的触点。
- 对话记录 –捕获包含联系人的消息线程并保持频道上下文。
- 呼叫记录 –使用快速笔记和时间戳跟踪电话交谈。
- 组管理 –策划联络小组，并审查谁属于其中。
- 提醒日程安排 –设置重复的推送，这样你就可以按时跟进人们。
- 任务管理 –添加跟进、更新状态或将任务重定向到正确的联系人。
- 笔记捕获 –根据助手提示创建和管理日记笔记。
- 标签系统 –使用自定义标签组织和分类联系人。
- 联系资源 –将Monica的联系方式和最近的笔记作为MCP资源进行流式传输。
- 任务可见性 –在全球或每个联系人中显示未完成/已完成的任务。
- 连接探头 –用于调试凭据的快速健康检查工具。
先决条件
- Node.js 18或更新版本。
- 带有API令牌的Monica CRM实例（自托管或托管）。
- 可选：如果您仍然依赖传统用户令牌
X-Auth-Token/X-User-Tokenauth。
安装
npm install配置
创建一个 .env 文件（或以其他方式设置环境变量）至少包含：
MONICA_API_TOKEN=your-token
# Defaults to https://app.monicahq.com; change for self-hosted instances
MONICA_BASE_URL=https://app.monicahq.com
# one of: bearer (default), apiKey, legacy
MONICA_TOKEN_TYPE=bearer
# Required only when MONICA_TOKEN_TYPE=legacy
MONICA_USER_TOKEN=optional-legacy-user-token
# Optional pino log level (fatal|error|warn|info|debug|trace|silent)
LOG_LEVEL=info运行服务器
- 开发：
npm run dev - 类型检查：
npm run typecheck - 构建：
npm run build - 开始（编译）：
npm run start
这 dev 脚本通过stdio启动MCP服务器，并实时重新加载以进行本地测试（例如使用 mcp-cli).
Claude桌面集成
将提供者添加到您的Claude桌面 ~/.claude-desktop/config.json （或每个平台路径的等效值）：
{
"mcpServers": {
"monica-crm": {
"command": "node",
"args": ["/absolute/path/to/monica-crm-mcp/dist/index.js"],
"env": {
"MONICA_API_TOKEN": "your-token",
"MONICA_BASE_URL": "https://app.monicahq.com"
}
}
}
}对于开发，您可以交换 node dist/index.js 随着 npm run dev --silent 直接使用TypeScript入口点。
暴露的工具
此Monica MCP服务器提供 21工具 涵盖最常见的CRM操作：
| 工具 | 目的 |
|---|---|
| 核心联系人管理 | |
monica_search_contacts | 按姓名、昵称或电子邮件搜索Monica CRM联系人。返回下游工具的联系人ID和基本信息。 |
monica_list_contacts | 无需搜索查询即可检索分页联系人列表。支持多个细节层和可选过滤器（性别、标签、通信接触点）。 |
monica_manage_contact | 检索摘要或管理配置文件字段、通信详细信息和地址 section 参数。 |
monica_manage_contact_profile | 简化的包装器，用于创建/更新/删除联系人资料（委托给 monica_manage_contact 随着 section="profile"). |
monica_manage_contact_field | 简化的包装器，用于列出/获取/创建/更新/删除电子邮件和电话等联系人字段（委托给 monica_manage_contact 随着 section="field"). |
monica_manage_contact_address | 简化的包装器，用于列出/获取/创建/更新/删除联系人地址（委托给 monica_manage_contact 随着 section="address"). |
monica_manage_contact_field_type | 管理Monica联系人字段类型（列表/获取/创建/更新/删除），以便您可以添加新的社交或自定义字段类型，如“Instagram”。 |
monica_manage_contact_tags | 管理联系人的标签分配（列表/附加/删除），以便您可以附加“亲密朋友”等标签。 |
| 沟通与互动 | |
monica_manage_conversation | 管理对话及其消息（列表/获取/创建/更新/删除以及消息添加/更新/移除）。通道可以通过ID或名称提供。 |
monica_manage_call | 记录与联系人的通话（列表/获取/创建/更新/删除），以快速记录电话笔记。 |
monica_manage_activity | 与联系人跟踪会议/活动。接受其中之一 activityTypeId 或 activityTypeName. |
monica_manage_note | 列出、检查、创建、更新或删除附加到联系人的笔记。 |
| 规划和跟进 | |
monica_manage_task_reminder | 一起管理Monica任务和提醒——选择要列出/获取/创建/更新/删除任一资源的项目类型。 |
monica_manage_financial_record | 用一套工具管理莫妮卡的礼物和债务 recordType “礼物”或“债务”）。 |
| 媒体和文件 | |
monica_manage_media | 管理Monica的文件和照片（集 mediaType “文件”或“照片”；支持使用文件路径或base64输入的list/get/upload/delete）。 |
| 关系与组织 | |
monica_manage_relationship | 列出、检查、创建、更新或删除联系人之间的关系。接受其中之一 relationshipTypeId 或 relationshipTypeName. |
monica_manage_group | 列出、检查、创建、更新或删除联系人组并查看其成员。 |
monica_manage_tag | 列出、检查、创建、更新或删除用于对联系人进行分类的标签。 |
| 元数据和系统 | |
monica_manage_activity_type | 管理Monica活动类型（列表/获取/创建/更新/删除），以便在记录活动之前添加“用餐”等条目。 |
monica_browse_metadata | 使用可选的名称过滤浏览Monica目录（性别、国家、联系人字段类型、活动类型、关系类型） |
monica_health_check | 验证配置的Monica凭据是否有效 |
暴露的资源
| 资源URI | 描述 |
|---|---|
monica-contact://{contactId} | 包含标准化联系人配置文件数据的JSON有效载荷。 |
monica-contact-notes://{contactId} | JSON有效载荷，包含联系人的最新注释。 |
每个资源都支持自动完成 contactId 通过Monica搜索，助手可以发现相关的ID。
可观察性和安全性
- 结构化日志记录
pino，并进行标记编辑。 - 默认情况下，请求的超时时间为15秒。
- Monica的错误被包装为工具输出（而不是协议错误），以便助手可以自我纠正。
- 集
MCP_LOG_FILE=/path/to/monica-mcp.log如果您希望服务器将日志镜像到磁盘，同时保持MCP的stdout干净。
下一步行动
- 根据需要扩大工具覆盖范围（活动、提醒、礼物）。
- 为繁重的工作区添加缓存或速率限制。
- 将服务器打包为可执行文件，以便于分发。
参见 docs/architecture.md 以获得更深入的设计演练和从上游文档中提取的Monica API参考。