内容
# Keepsake-MCP
Keepsake 的 MCP 服务器 —— 一个帮助您培养人际关系的个人 CRM。
将您的 AI 助手（Claude、Cursor 或任何兼容 MCP 的客户端）连接到您的 Keepsake 数据：联系人、互动、任务、笔记、日常日记、公司和标签。
## 为什么
您的 AI 助手成为个人关系管理器。询问它：
- "我上次与 Acme Corp 交谈的人是谁？"
- "添加一个笔记，记录我在会议上遇到的 Sarah"
- "哪些任务已逾期？"
- "为我显示与 #house-project 标签相关的所有内容"
- "为下周与 John 的会议创建后续任务"
## 快速入门
### 1. 获取您的 API 密钥
在 [keepsake.place](https://keepsake.place) 注册，然后前往 **账户 > API 密钥** 以生成一个。
### 2. 选择您的连接方式
#### 选项 A：远程（HTTP）—— 推荐
无需安装。适用于 Claude iOS、Claude 网页版、Claude 桌面连接器以及任何支持 Streamable HTTP 的 MCP 客户端。
**端点：** `https://app.keepsake.place/api/mcp`
**身份验证：** 在 `Authorization` 头部中传递您的 API 密钥作为 Bearer 令牌。
**Claude 桌面（连接器）：**
在 Claude 桌面设置中添加远程 MCP 服务器，配置如下：
- URL：`https://app.keepsake.place/api/mcp`
- 身份验证：带有 `ksk_` API 密钥的 Bearer 令牌
**任何 MCP 客户端（Streamable HTTP）：**
```json
{
"mcpServers": {
"keepsake": {
"type": "streamable-http",
"url": "https://app.keepsake.place/api/mcp",
"headers": {
"Authorization": "Bearer ksk_YOUR_API_KEY"
}
}
}
}
```
#### 选项 B：本地（stdio）
通过 `npx` 在本地运行。适用于 Claude Code、Cursor 和本地开发。
**Claude 桌面：**
将以下配置添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"keepsake": {
"command": "npx",
"args": ["-y", "keepsake-mcp"],
"env": {
"KEEPSAKE_API_KEY": "ksk_YOUR_API_KEY"
}
}
}
}
```
**Claude 代码：**
```bash
claude mcp add keepsake -- npx -y keepsake-mcp
```
然后在您的环境中设置 `KEEPSAKE_API_KEY`。
**Cursor：**
将以下配置添加到项目中的 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"keepsake": {
"command": "npx",
"args": ["-y", "keepsake-mcp"],
"env": {
"KEEPSAKE_API_KEY": "ksk_YOUR_API_KEY"
}
}
}
}
```
## 可用工具（58）
### 联系人
| 工具 | 描述 |
|------|-------------|
| `list_contacts` | 列出所有联系人，支持分页和排序 |
| `get_contact` | 获取联系人及其最近的互动、标签和统计信息 |
| `create_contact` | 创建新联系人 |
| `update_contact` | 更新联系人信息 |
| `delete_contact` | 永久删除联系人 |
| `search_contacts` | 按姓名、电子邮件、公司进行不区分重音的搜索 |
| `get_contact_timeline` | 联系人的统一时间轴 |
### 公司
| 工具 | 描述 |
|------|-------------|
| `list_companies` | 列出所有公司 |
| `get_company` | 获取公司及其关联的联系人和标签 |
| `create_company` | 创建新公司 |
| `update_company` | 更新公司信息 |
| `delete_company` | 软删除（或永久删除）公司 |
| `search_companies` | 不区分重音的公司搜索 |
### 条目（互动）
| 工具 | 描述 |
|------|-------------|
| `list_entries` | 列出互动（通话、电子邮件、会议等） |
| `create_entry` | 记录新的互动 — 支持 `#tag#` 和 `[[tag]]` 语法 |
| `update_entry` | 更新互动 |
| `delete_entry` | 删除互动 |
### 任务
| 工具 | 描述 |
|------|-------------|
| `list_tasks` | 列出任务，支持状态/日期筛选 |
| `create_task` | 创建任务 — 支持 `#tag#` 和 `[[tag]]` 语法 |
| `update_task` | 更新任务信息 |
| `delete_task` | 删除任务 |
| `complete_task` | 标记为完成（自动为重复任务创建下一个事件） |
| `uncomplete_task` | 标记为待处理 |
| `snooze_task` | 重新安排到新日期 |
| `get_tasks_today` | 今日任务：逾期 + 今日到期 + ASAP |
| `get_tasks_overdue` | 仅逾期任务 |
### 快速笔记
| 工具 | 描述 |
|------|-------------|
| `list_notes` | 列出笔记（支持筛选已固定/已归档） |
| `create_note` | 创建笔记 — 支持 `#tag#` 和 `[[tag]]` 语法 |
| `update_note` | 更新笔记内容 |
| `delete_note` | 软删除（或永久删除） |
| `pin_note` | 固定到顶部 |
| `archive_note` | 归档笔记 |
| `restore_note` | 恢复已删除/已归档的笔记 |
### 每日日记
| 工具 | 描述 |
|------|-------------|
| `list_days` | 按日期范围列出日记条目 |
| `get_day` | 获取特定日期的日记 |
| `update_day` | 创建或更新日记（插入/更新） |
### 标签
| 工具 | 描述 |
|------|-------------|
| `list_tags` | 列出所有标签 |
| `get_tag` | 获取标签及其所有属性（颜色、图标、视图模式等） |
| `create_tag` | 创建新标签 |
| `update_tag` | 更新标签（名称、描述、颜色、图标、视图模式、收藏） |
| `delete_tag` | 永久删除标签及其所有链接 |
| `get_tag_items` | 获取与标签关联的所有内容 |
| `link_tag` | 将任何实体链接到标签 |
| `unlink_tag` | 删除标签链接 |
### 任务头（章节）
| 工具 | 描述 |
|------|-------------|
| `list_task_headers` | 列出所有任务头（章节分隔符） |
| `get_task_header` | 获取任务头 |
| `create_task_header` | 创建任务头（章节） |
| `update_task_header` | 更新任务头（名称、描述、折叠） |
| `delete_task_header` | 永久删除任务头 |
### 联系人链接
| 工具 | 描述 |
|------|-------------|
| `link_note_contact` | 将联系人链接到笔记 |
| `unlink_note_contact` | 从笔记中删除联系人链接 |
| `link_entry_contact` | 将联系人链接到条目 |
| `unlink_entry_contact` | 从条目中删除联系人链接 |
| `link_task_contact` | 将联系人链接到任务 |
| `unlink_task_contact` | 从任务中删除联系人链接 |
### 实用工具
| 工具 | 描述 |
|------|-------------|
| `search` | 跨所有数据类型进行全局搜索 |
| `get_changelog` | 获取自指定时间戳以来修改的项目（用于同步） |
| `get_agent_instructions` | AI 代理最佳实践 |
## 工具注释
所有工具都包含 MCP 安全注释：
- **只读工具**（`list_*`、`get_*`、`search_*`）：标记为 `readOnlyHint: true`
- **创建工具**：标记为 `destructiveHint: false`
- **更新工具**：标记为 `destructiveHint: false, idempotentHint: true`
- **删除工具**：标记为 `destructiveHint: true, idempotentHint: true`
## 活动跟踪
通过 API 执行的每个写入操作（创建、更新、删除）都会在 Keepsake 中用户可见的 **活动馈流** 中记录。每个操作都会显示实体类型、内容预览以及所使用的 API 密钥。
这意味着您的用户可以看到您执行的所有操作。请透明和精确。如果您犯了错误，请让用户知道，以便他们可以在活动馈流中验证。
在每次会话开始时调用 `get_agent_instructions` 以获取完整最佳实践指南。
## 环境变量
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `KEEPSAKE_API_KEY` | 是 | 您的 API 密钥（以 `ksk_` 开头） |
| `KEEPSAKE_API_URL` | 否 | 自定义 API URL（默认为 `https://app.keepsake.place/api/v1`） |
## 速率限制
每个 API 密钥每分钟 60 个请求。响应中包含速率限制头部。
## API 文档
完整的 REST API 文档：[keepsake.place/api](https://keepsake.place/en/api)
## 隐私
Keepsake MCP 服务器仅与 Keepsake API (`app.keepsake.place`) 通信。不会将数据发送到任何第三方服务。您的数据保留在您的 MCP 客户端和您的 Keepsake 帐户之间。
所有 API 调用都使用您的个人 API 密钥进行身份验证，并通过行级安全范围限定到您的帐户。其他用户的任何数据都不可访问。
请参阅我们的隐私政策：[keepsake.place/privacy](https://keepsake.place/en/privacy)
## 许可证
MIT
