尧图网页设计 
Karakeep MCP 服务器接入指南用 Claude 等 LLM 直接搜索与管理你的书签库【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarderKarakeep原 Hoarder自带一个 Model Context ProtocolMCP服务器可以让 Claude Desktop 等支持 MCP 的 LLM 客户端直接读写你的书签库——搜索书签、创建链接/文本书签、维护列表与标签、管理高亮全部通过自然语言完成。本文以 docs/versioned_docs/version-v0.29.0/09-mcp.md 为骨架结合 apps/mcp 下的真实源码完整讲解 MCP 服务器的能力清单、Claude Desktop 接入配置、每个工具的入参与行为以及 API Key 的生成与权限作用域。读完本文你将能在一台自托管的 Karakeep 实例上把书签库交给 LLM 直接操作并理解其底层调用链。一、Karakeep MCP 服务器能做什么Karakeep 的 MCP 服务器是一个独立的 Node.js 程序通过标准输入输出stdio与 MCP 客户端通信。它面向 LLM 暴露了一组工具Tools覆盖书签库的日常操作搜索书签支持全文、语义、混合三种检索策略读取、创建、更新、删除书签创建列表把书签加入/移出列表给书签附加/摘除标签管理标签本身获取资源的临时签名下载链接列出、创建、更新、删除高亮Highlights与当前仓库实现对应MCP 服务器只暴露工具Tools不暴露资源Resources——这一点在 apps/mcp/README.md 中有明确说明Currently, the MCP server only exposes tools (no resources)。二、接入前置条件API 地址与 API KeyMCP 服务器本身不直接连数据库它通过 Karakeep 的 HTTP API 与你的实例通信。因此接入前需要准备两样东西环境变量必填说明KARAKEEP_API_ADDR是你的 Karakeep 实例地址例如https://karakeep.example.comKARAKEEP_API_KEY是在 Web 界面生成的 API KeyBearer TokenKARAKEEP_CUSTOM_HEADERS否可选的额外请求头JSON 字符串例如 Cloudflare Access 的CF-Access-Client-Id/CF-Access-Client-Secret从源码看客户端实际请求的基地址是${KARAKEEP_API_ADDR}/api/v1并在每个请求头中带上authorization: Bearer ${apiKey}与Content-Type: application/jsonKARAKEEP_CUSTOM_HEADERS会被JSON.parse后合并进请求头见 apps/mcp/src/shared.ts。如果自定义头解析失败服务器会打印错误并回退为空对象不会崩溃。2.1 如何生成 API Key在 Karakeep Web 界面中进入Settings → API Keys对应路由为/settings/api-keys见 apps/web/app/settings/layout.tsx点击创建即可生成。创建时可以选择两种权限模式Full accessfullaccess拥有全部资源的读写权限配置最简单适合个人自托管实例自定义作用域Scoped按资源维度assets、backups、bookmarks、feeds、highlights、lists、prompts、rules、tags、users、webhooks等分别授予read或readwrite权限管理员还可以授予admin:resource:access形式的管理员作用域。作用域定义与校验逻辑集中在 packages/shared/types/apiKeys.tsAPI_KEY_SCOPE_RESOURCES列出全部资源API_KEY_SCOPE_ACCESS为[read, readwrite]apiKeyScopesGrantScope函数实现授权判定——持有fullaccess直接放行持有readwrite的请求也满足对应的read需求。API Key 的创建界面实现见 apps/web/components/settings/AddApiKey.tsx作用域选项的构建见 apps/web/components/settings/apiKeyScopes.ts。安全建议若实例被公网访问建议使用自定义作用域仅授予 MCP 实际用到的资源如bookmarks:readwrite、lists:readwrite、tags:readwrite降低 Key 泄露时的爆炸半径。请求鉴权由 packages/api/middlewares/apiKeyScopes.ts 与 packages/api/middlewares/auth.ts 在服务端强制执行。三、与 Claude Desktop 集成Karakeep 官方文档提供了两种接入 Claude Desktop 的方式都通过编辑 Claude Desktop 的配置文件claude_desktop_config.json完成。3.1 方式一通过 NPMnpx{ mcpServers: { karakeep: { command: npx, args: [ karakeep/mcp ], env: { KARAKEEP_API_ADDR: https://YOUR_SERVER_ADDR, KARAKEEP_API_KEY: YOUR_TOKEN } } } }npx 方式要求本机能访问 npm registry首次运行会自动拉取并缓存karakeep/mcp包。该包声明了bin入口karakeep-mcp见 apps/mcp/package.json因此也可以直接使用npx karakeep/mcp手动启动验证。3.2 方式二通过 Docker{ mcpServers: { karakeep: { command: docker, args: [ run, -e, KARAKEEP_API_ADDRhttps://YOUR_SERVER_ADDR, -e, KARAKEEP_API_KEYYOUR_TOKEN, ghcr.io/karakeep-app/karakeep-mcp:latest ] } } }Docker 方式需要本机安装 Docker镜像由 Karakeep 官方发布在ghcr.io/karakeep-app/karakeep-mcp。两种方式等价选择哪种取决于你的运行环境。3.3 带自定义请求头的配置如果你的 Karakeep 实例位于 Cloudflare Access 等网关之后需要携带额外的鉴权头可以追加KARAKEEP_CUSTOM_HEADERS环境变量完整示例见 apps/mcp/README.md{ mcpServers: { karakeep: { command: npx, args: [karakeep/mcp], env: { KARAKEEP_API_ADDR: https://YOUR_SERVER_ADDR, KARAKEEP_API_KEY: YOUR_TOKEN, KARAKEEP_CUSTOM_HEADERS: {\CF-Access-Client-Id\: \...\, \CF-Access-Client-Secret\: \...\} } } } }注意KARAKEEP_CUSTOM_HEADERS是一个 JSON 字符串在 JSON 配置文件中需要对其中的双引号进行转义\。3.4 演示效果以下是官方文档给出的使用演示动图来自 docs/static/mcp-1.gif、docs/static/mcp-2.gif、docs/static/mcp-3.gif搜索书签添加文本书签添加 URL 书签四、工具详解当前仓库中 MCP 服务器共注册了约 30 个工具按模块组织在 apps/mcp 目录下入口 apps/mcp/src/index.ts 依次导入assets.ts、bookmarks.ts、highlights.ts、lists.ts、tags.ts完成注册。下面按模块逐一说明。4.1 书签模块apps/mcp/src/bookmarks.ts工具功能关键入参search-bookmarks全文/语义/混合搜索书签query、limit默认 10、nextCursor、sortOrder、searchModeget-bookmark按 id 读取书签元数据bookmarkIdget-bookmark-content获取书签正文转成 MarkdownbookmarkIdget-bookmark-lists列出书签所属的列表bookmarkIdcreate-bookmark创建链接或文本书签typelink/text、title、contentupdate-bookmark更新书签字段只更新传入字段bookmarkId及可选字段delete-bookmark删除书签连同高亮和资源bookmarkIdsearch-bookmarks的query支持一整套查询限定语法qualifiers这是 MCP 中最值得掌握的能力。从 apps/mcp/src/bookmarks.ts 的入参描述中可以整理出完整语法限定符含义is:fav只看收藏书签is:archived只看已归档书签is:tagged只看带标签的书签is:inlist只看在列表中的书签is:link/is:text/is:media按书签类型过滤url:value按 URL 子串匹配#tag匹配带有某标签的书签list:name匹配位于某列表的书签按名称不带图标after:date/before:date按创建日期过滤YYYY-MM-DD组合规则带空格的名字用双引号包裹在限定符前加减号-表示取反支持and/or布尔运算符与括号分组。例如查找 2023 年收藏且打上important标签的书签is:fav after:2023-01-01 before:2023-12-31 #important查找归档中位于reading列表或带work标签的书签is:archived and (list:reading or #work)全文搜索与限定符组合machine learning is:favsearch-bookmarks还支持分页首次调用后返回结果末尾会给出Next cursor: cursor把该值作为nextCursor传入即可取下一页。排序方面sortOrder可选asc/desc/relevance默认relevancesearchMode可选fts全文/semantic语义向量/hybrid混合默认fts其中semantic与hybrid只支持按相关性排序。create-bookmark通过type区分两种创建link类型把content当作 URLtext类型把content当作要保存的文本正文见 apps/mcp/src/bookmarks.ts。get-bookmark-content则针对链接书签把 HTML 用 Turndown 服务转为 Markdown 返回文本书签直接返回正文媒体书签返回其内容文本apps/mcp/src/bookmarks.ts。4.2 列表模块apps/mcp/src/lists.ts工具功能关键入参get-lists列出全部列表无get-list按 id 读取单个列表listIdcreate-list创建列表name、icon、parentId可选update-list更新列表字段listIdname/icon/description/parentId/query/publicdelete-list删除列表listIdget-list-bookmarks列出列表内的书签智能列表按其保存的 query 求值listId、sortOrder、limit、cursor、includeContentadd-bookmark-to-list把书签加入列表listId、bookmarkIdremove-bookmark-from-list把书签移出列表listId、bookmarkId几点值得注意的行为update-list的字段约束名称长度上限、智能列表 query 校验直接复用共享的zEditBookmarkListSchemaWithValidationschemaMCP 端在调用前会先做本地校验apps/mcp/src/lists.tsdelete-list不会删除列表内的书签也不会删除子列表——子列表会变成根级列表parentId置空。如果想调整树形结构应先把子列表移动或重新挂载后再删除工具描述中对此有明确提醒apps/mcp/src/lists.tsget-list-bookmarks返回结果末尾带Next page cursor配合cursor参数翻页includeContent控制是否附带书签全文apps/mcp/src/lists.ts。4.3 标签模块apps/mcp/src/tags.ts工具功能关键入参get-tags列出标签带书签计数、支持过滤分页nameContains、sort、attachedBy、cursor、limitget-tag读取单个标签及计数tagIdupdate-tag重命名标签服务端会做规范化tagId、namedelete-tag删除标签不打标签关联的书签tagIdget-tag-bookmarks列出挂有某标签的书签tagId、sortOrder、limit、cursor、includeContentattach-tag-to-bookmark给书签附加标签bookmarkId、tagsToAttach标签名数组detach-tag-from-bookmark从书签摘除标签bookmarkId、tagsToDetach标签名数组get-tags的sort可选name/usage/relevance默认usage其中relevance要求提供nameContainsattachedBy可选ai/human/none用于区分 AI 自动打的标签和人工标签。compactTag输出会同时给出总书签数与人工/AI 各自计数见 apps/mcp/src/utils.ts便于 LLM 理解标签的覆盖面。attach-tag-to-bookmark按标签名批量附加即使标签不存在也会由服务端创建。4.4 资源模块apps/mcp/src/assets.ts工具功能关键入参get-asset获取资源图片等附件的临时签名下载链接assetId该工具调用/assets/{assetId}/signed-url接口返回signedUrl与expiresAtLLM 拿到签名 URL 后可在有效期内直接下载资源内容apps/mcp/src/assets.ts。4.5 高亮模块apps/mcp/src/highlights.ts工具功能关键入参list-highlights列出全部书签的高亮新的在前limit、cursorget-bookmark-highlights列出某书签上的全部高亮bookmarkIdget-highlight读取单个高亮highlightIdcreate-highlight创建高亮基于可读内容的字符偏移bookmarkId、startOffset、endOffset、color、text、noteupdate-highlight修改高亮颜色或备注highlightId、color、notedelete-highlight删除高亮highlightIdcreate-highlight的偏移语义是零基、起始包含、结束排他startOffset为包含的起始字符下标endOffset为排他的结束下标必须大于startOffset见 apps/mcp/src/highlights.ts颜色可选yellow/red/green/blue默认yellow。4.6 输出格式约定所有工具的输出都经过 apps/mcp/src/utils.ts 中的compactBookmark/compactList/compactTag/compactHighlight压缩成纯文本例如书签会输出 ID、创建/修改时间、标题、归档/收藏状态、标签、资源列表、标签化/摘要/向量化状态等字段。这种压缩文本设计让 LLM 能在一次响应中消化更多结果如需正文内容再显式调用get-bookmark-content或设置includeContent。调用出错时工具会通过toMcpToolError返回带isError: true的错误结果apps/mcp/src/utils.ts。五、底层工作原理MCP 服务器的实现非常精简理解它有助于排查接入问题进程入口apps/mcp/src/index.ts使用serveStdio(createMcpServer)启动 stdio 传输的 MCP 服务器这是 Claude Desktop 等桌面客户端最常用的传输方式服务器装配createMcpServer创建名为Karakeep的McpServer实例版本号取自package.json然后把各模块通过registerTool注册的全部工具逐一挂载apps/mcp/src/shared.tsAPI 客户端服务器通过createKarakeepClient来自karakeep/sdk包生成类型安全的 API 客户端基地址为${KARAKEEP_API_ADDR}/api/v1每个工具回调本质上是一次 HTTP 请求GET/POST/PATCH/PUT/DELETE到 Karakeep 的 REST APIapps/mcp/src/shared.ts入参校验工具入参统一用 zod schema 描述MCP 客户端LLM会依据这些 schema 生成参数服务端在回调前完成类型校验只读提示get-bookmark-lists、get-list-bookmarks、list-highlights等纯查询工具标注了readOnlyHint: truedelete-bookmark、delete-highlight等破坏性操作标注了destructiveHint/idempotentHint见 apps/mcp/src/highlights.ts这些注解会帮助客户端在调用前向用户确认破坏性操作。从调用链看MCP 层不直接触碰数据库而是完整复用 Karakeep 的 REST API路由定义见 packages/api/routes因此 API Key 的作用域限制、服务端校验、审计逻辑对 MCP 调用同样生效——这也是推荐使用自定义作用域 Key 的原因。六、接入后的典型用法与注意事项6.1 典型用法接入成功后你可以直接用自然语言下达指令例如搜索 2024 年收藏、带AI标签的链接书签 → 触发search-bookmarksis:link #AI after:2024-01-01把这篇文章保存为书签附上 URL→ 触发create-bookmarktype: link把这段文字记到书签里 → 触发create-bookmarktype: text新建一个叫 待读 的列表图标用 → 触发create-list给书签 xxx 打上work标签并加入reading列表 → 触发attach-tag-to-bookmarkadd-bookmark-to-list6.2 注意事项Token 保护API Key 会以环境变量形式写入客户端配置请勿把claude_desktop_config.json提交到公开仓库破坏性操作delete-bookmark会连同书签的高亮与资源一起删除delete-list、delete-tag虽然不删内容但会改变组织结构涉及删除的指令建议先在对话中让 LLM 展示将要操作的对象再确认执行分页书签、标签、高亮、列表书签的列表类工具都支持 cursor 分页一次只返回一页默认 10 条需要完整遍历时应按返回的 cursor 连续调用自定义头如果你的实例在反向代理/网关后面务必通过KARAKEEP_CUSTOM_HEADERS传入代理要求的鉴权头否则 API 调用会被网关拦截。七、延伸阅读MCP 服务器的完整工具清单与 READMEapps/mcp/README.mdMCP 服务器源码apps/mcp/srcAPI Key 作用域定义packages/shared/types/apiKeys.tsAPI Key 创建界面apps/web/components/settings/AddApiKey.tsx服务端 API 路由packages/api/routesKarakeep 其他集成方式命令行、RSS、Agent 技能docs/docs/05-integrations【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Karakeep MCP 服务器接入指南：用 Claude 等 LLM 直接搜索与管理你的书签库
Karakeep MCP 服务器接入指南用 Claude 等 LLM 直接搜索与管理你的书签库【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarderKarakeep原 Hoarder自带一个 Model Context ProtocolMCP服务器可以让 Claude Desktop 等支持 MCP 的 LLM 客户端直接读写你的书签库——搜索书签、创建链接/文本书签、维护列表与标签、管理高亮全部通过自然语言完成。本文以 docs/versioned_docs/version-v0.29.0/09-mcp.md 为骨架结合 apps/mcp 下的真实源码完整讲解 MCP 服务器的能力清单、Claude Desktop 接入配置、每个工具的入参与行为以及 API Key 的生成与权限作用域。读完本文你将能在一台自托管的 Karakeep 实例上把书签库交给 LLM 直接操作并理解其底层调用链。一、Karakeep MCP 服务器能做什么Karakeep 的 MCP 服务器是一个独立的 Node.js 程序通过标准输入输出stdio与 MCP 客户端通信。它面向 LLM 暴露了一组工具Tools覆盖书签库的日常操作搜索书签支持全文、语义、混合三种检索策略读取、创建、更新、删除书签创建列表把书签加入/移出列表给书签附加/摘除标签管理标签本身获取资源的临时签名下载链接列出、创建、更新、删除高亮Highlights与当前仓库实现对应MCP 服务器只暴露工具Tools不暴露资源Resources——这一点在 apps/mcp/README.md 中有明确说明Currently, the MCP server only exposes tools (no resources)。二、接入前置条件API 地址与 API KeyMCP 服务器本身不直接连数据库它通过 Karakeep 的 HTTP API 与你的实例通信。因此接入前需要准备两样东西环境变量必填说明KARAKEEP_API_ADDR是你的 Karakeep 实例地址例如https://karakeep.example.comKARAKEEP_API_KEY是在 Web 界面生成的 API KeyBearer TokenKARAKEEP_CUSTOM_HEADERS否可选的额外请求头JSON 字符串例如 Cloudflare Access 的CF-Access-Client-Id/CF-Access-Client-Secret从源码看客户端实际请求的基地址是${KARAKEEP_API_ADDR}/api/v1并在每个请求头中带上authorization: Bearer ${apiKey}与Content-Type: application/jsonKARAKEEP_CUSTOM_HEADERS会被JSON.parse后合并进请求头见 apps/mcp/src/shared.ts。如果自定义头解析失败服务器会打印错误并回退为空对象不会崩溃。2.1 如何生成 API Key在 Karakeep Web 界面中进入Settings → API Keys对应路由为/settings/api-keys见 apps/web/app/settings/layout.tsx点击创建即可生成。创建时可以选择两种权限模式Full accessfullaccess拥有全部资源的读写权限配置最简单适合个人自托管实例自定义作用域Scoped按资源维度assets、backups、bookmarks、feeds、highlights、lists、prompts、rules、tags、users、webhooks等分别授予read或readwrite权限管理员还可以授予admin:resource:access形式的管理员作用域。作用域定义与校验逻辑集中在 packages/shared/types/apiKeys.tsAPI_KEY_SCOPE_RESOURCES列出全部资源API_KEY_SCOPE_ACCESS为[read, readwrite]apiKeyScopesGrantScope函数实现授权判定——持有fullaccess直接放行持有readwrite的请求也满足对应的read需求。API Key 的创建界面实现见 apps/web/components/settings/AddApiKey.tsx作用域选项的构建见 apps/web/components/settings/apiKeyScopes.ts。安全建议若实例被公网访问建议使用自定义作用域仅授予 MCP 实际用到的资源如bookmarks:readwrite、lists:readwrite、tags:readwrite降低 Key 泄露时的爆炸半径。请求鉴权由 packages/api/middlewares/apiKeyScopes.ts 与 packages/api/middlewares/auth.ts 在服务端强制执行。三、与 Claude Desktop 集成Karakeep 官方文档提供了两种接入 Claude Desktop 的方式都通过编辑 Claude Desktop 的配置文件claude_desktop_config.json完成。3.1 方式一通过 NPMnpx{ mcpServers: { karakeep: { command: npx, args: [ karakeep/mcp ], env: { KARAKEEP_API_ADDR: https://YOUR_SERVER_ADDR, KARAKEEP_API_KEY: YOUR_TOKEN } } } }npx 方式要求本机能访问 npm registry首次运行会自动拉取并缓存karakeep/mcp包。该包声明了bin入口karakeep-mcp见 apps/mcp/package.json因此也可以直接使用npx karakeep/mcp手动启动验证。3.2 方式二通过 Docker{ mcpServers: { karakeep: { command: docker, args: [ run, -e, KARAKEEP_API_ADDRhttps://YOUR_SERVER_ADDR, -e, KARAKEEP_API_KEYYOUR_TOKEN, ghcr.io/karakeep-app/karakeep-mcp:latest ] } } }Docker 方式需要本机安装 Docker镜像由 Karakeep 官方发布在ghcr.io/karakeep-app/karakeep-mcp。两种方式等价选择哪种取决于你的运行环境。3.3 带自定义请求头的配置如果你的 Karakeep 实例位于 Cloudflare Access 等网关之后需要携带额外的鉴权头可以追加KARAKEEP_CUSTOM_HEADERS环境变量完整示例见 apps/mcp/README.md{ mcpServers: { karakeep: { command: npx, args: [karakeep/mcp], env: { KARAKEEP_API_ADDR: https://YOUR_SERVER_ADDR, KARAKEEP_API_KEY: YOUR_TOKEN, KARAKEEP_CUSTOM_HEADERS: {\CF-Access-Client-Id\: \...\, \CF-Access-Client-Secret\: \...\} } } } }注意KARAKEEP_CUSTOM_HEADERS是一个 JSON 字符串在 JSON 配置文件中需要对其中的双引号进行转义\。3.4 演示效果以下是官方文档给出的使用演示动图来自 docs/static/mcp-1.gif、docs/static/mcp-2.gif、docs/static/mcp-3.gif搜索书签添加文本书签添加 URL 书签四、工具详解当前仓库中 MCP 服务器共注册了约 30 个工具按模块组织在 apps/mcp 目录下入口 apps/mcp/src/index.ts 依次导入assets.ts、bookmarks.ts、highlights.ts、lists.ts、tags.ts完成注册。下面按模块逐一说明。4.1 书签模块apps/mcp/src/bookmarks.ts工具功能关键入参search-bookmarks全文/语义/混合搜索书签query、limit默认 10、nextCursor、sortOrder、searchModeget-bookmark按 id 读取书签元数据bookmarkIdget-bookmark-content获取书签正文转成 MarkdownbookmarkIdget-bookmark-lists列出书签所属的列表bookmarkIdcreate-bookmark创建链接或文本书签typelink/text、title、contentupdate-bookmark更新书签字段只更新传入字段bookmarkId及可选字段delete-bookmark删除书签连同高亮和资源bookmarkIdsearch-bookmarks的query支持一整套查询限定语法qualifiers这是 MCP 中最值得掌握的能力。从 apps/mcp/src/bookmarks.ts 的入参描述中可以整理出完整语法限定符含义is:fav只看收藏书签is:archived只看已归档书签is:tagged只看带标签的书签is:inlist只看在列表中的书签is:link/is:text/is:media按书签类型过滤url:value按 URL 子串匹配#tag匹配带有某标签的书签list:name匹配位于某列表的书签按名称不带图标after:date/before:date按创建日期过滤YYYY-MM-DD组合规则带空格的名字用双引号包裹在限定符前加减号-表示取反支持and/or布尔运算符与括号分组。例如查找 2023 年收藏且打上important标签的书签is:fav after:2023-01-01 before:2023-12-31 #important查找归档中位于reading列表或带work标签的书签is:archived and (list:reading or #work)全文搜索与限定符组合machine learning is:favsearch-bookmarks还支持分页首次调用后返回结果末尾会给出Next cursor: cursor把该值作为nextCursor传入即可取下一页。排序方面sortOrder可选asc/desc/relevance默认relevancesearchMode可选fts全文/semantic语义向量/hybrid混合默认fts其中semantic与hybrid只支持按相关性排序。create-bookmark通过type区分两种创建link类型把content当作 URLtext类型把content当作要保存的文本正文见 apps/mcp/src/bookmarks.ts。get-bookmark-content则针对链接书签把 HTML 用 Turndown 服务转为 Markdown 返回文本书签直接返回正文媒体书签返回其内容文本apps/mcp/src/bookmarks.ts。4.2 列表模块apps/mcp/src/lists.ts工具功能关键入参get-lists列出全部列表无get-list按 id 读取单个列表listIdcreate-list创建列表name、icon、parentId可选update-list更新列表字段listIdname/icon/description/parentId/query/publicdelete-list删除列表listIdget-list-bookmarks列出列表内的书签智能列表按其保存的 query 求值listId、sortOrder、limit、cursor、includeContentadd-bookmark-to-list把书签加入列表listId、bookmarkIdremove-bookmark-from-list把书签移出列表listId、bookmarkId几点值得注意的行为update-list的字段约束名称长度上限、智能列表 query 校验直接复用共享的zEditBookmarkListSchemaWithValidationschemaMCP 端在调用前会先做本地校验apps/mcp/src/lists.tsdelete-list不会删除列表内的书签也不会删除子列表——子列表会变成根级列表parentId置空。如果想调整树形结构应先把子列表移动或重新挂载后再删除工具描述中对此有明确提醒apps/mcp/src/lists.tsget-list-bookmarks返回结果末尾带Next page cursor配合cursor参数翻页includeContent控制是否附带书签全文apps/mcp/src/lists.ts。4.3 标签模块apps/mcp/src/tags.ts工具功能关键入参get-tags列出标签带书签计数、支持过滤分页nameContains、sort、attachedBy、cursor、limitget-tag读取单个标签及计数tagIdupdate-tag重命名标签服务端会做规范化tagId、namedelete-tag删除标签不打标签关联的书签tagIdget-tag-bookmarks列出挂有某标签的书签tagId、sortOrder、limit、cursor、includeContentattach-tag-to-bookmark给书签附加标签bookmarkId、tagsToAttach标签名数组detach-tag-from-bookmark从书签摘除标签bookmarkId、tagsToDetach标签名数组get-tags的sort可选name/usage/relevance默认usage其中relevance要求提供nameContainsattachedBy可选ai/human/none用于区分 AI 自动打的标签和人工标签。compactTag输出会同时给出总书签数与人工/AI 各自计数见 apps/mcp/src/utils.ts便于 LLM 理解标签的覆盖面。attach-tag-to-bookmark按标签名批量附加即使标签不存在也会由服务端创建。4.4 资源模块apps/mcp/src/assets.ts工具功能关键入参get-asset获取资源图片等附件的临时签名下载链接assetId该工具调用/assets/{assetId}/signed-url接口返回signedUrl与expiresAtLLM 拿到签名 URL 后可在有效期内直接下载资源内容apps/mcp/src/assets.ts。4.5 高亮模块apps/mcp/src/highlights.ts工具功能关键入参list-highlights列出全部书签的高亮新的在前limit、cursorget-bookmark-highlights列出某书签上的全部高亮bookmarkIdget-highlight读取单个高亮highlightIdcreate-highlight创建高亮基于可读内容的字符偏移bookmarkId、startOffset、endOffset、color、text、noteupdate-highlight修改高亮颜色或备注highlightId、color、notedelete-highlight删除高亮highlightIdcreate-highlight的偏移语义是零基、起始包含、结束排他startOffset为包含的起始字符下标endOffset为排他的结束下标必须大于startOffset见 apps/mcp/src/highlights.ts颜色可选yellow/red/green/blue默认yellow。4.6 输出格式约定所有工具的输出都经过 apps/mcp/src/utils.ts 中的compactBookmark/compactList/compactTag/compactHighlight压缩成纯文本例如书签会输出 ID、创建/修改时间、标题、归档/收藏状态、标签、资源列表、标签化/摘要/向量化状态等字段。这种压缩文本设计让 LLM 能在一次响应中消化更多结果如需正文内容再显式调用get-bookmark-content或设置includeContent。调用出错时工具会通过toMcpToolError返回带isError: true的错误结果apps/mcp/src/utils.ts。五、底层工作原理MCP 服务器的实现非常精简理解它有助于排查接入问题进程入口apps/mcp/src/index.ts使用serveStdio(createMcpServer)启动 stdio 传输的 MCP 服务器这是 Claude Desktop 等桌面客户端最常用的传输方式服务器装配createMcpServer创建名为Karakeep的McpServer实例版本号取自package.json然后把各模块通过registerTool注册的全部工具逐一挂载apps/mcp/src/shared.tsAPI 客户端服务器通过createKarakeepClient来自karakeep/sdk包生成类型安全的 API 客户端基地址为${KARAKEEP_API_ADDR}/api/v1每个工具回调本质上是一次 HTTP 请求GET/POST/PATCH/PUT/DELETE到 Karakeep 的 REST APIapps/mcp/src/shared.ts入参校验工具入参统一用 zod schema 描述MCP 客户端LLM会依据这些 schema 生成参数服务端在回调前完成类型校验只读提示get-bookmark-lists、get-list-bookmarks、list-highlights等纯查询工具标注了readOnlyHint: truedelete-bookmark、delete-highlight等破坏性操作标注了destructiveHint/idempotentHint见 apps/mcp/src/highlights.ts这些注解会帮助客户端在调用前向用户确认破坏性操作。从调用链看MCP 层不直接触碰数据库而是完整复用 Karakeep 的 REST API路由定义见 packages/api/routes因此 API Key 的作用域限制、服务端校验、审计逻辑对 MCP 调用同样生效——这也是推荐使用自定义作用域 Key 的原因。六、接入后的典型用法与注意事项6.1 典型用法接入成功后你可以直接用自然语言下达指令例如搜索 2024 年收藏、带AI标签的链接书签 → 触发search-bookmarksis:link #AI after:2024-01-01把这篇文章保存为书签附上 URL→ 触发create-bookmarktype: link把这段文字记到书签里 → 触发create-bookmarktype: text新建一个叫 待读 的列表图标用 → 触发create-list给书签 xxx 打上work标签并加入reading列表 → 触发attach-tag-to-bookmarkadd-bookmark-to-list6.2 注意事项Token 保护API Key 会以环境变量形式写入客户端配置请勿把claude_desktop_config.json提交到公开仓库破坏性操作delete-bookmark会连同书签的高亮与资源一起删除delete-list、delete-tag虽然不删内容但会改变组织结构涉及删除的指令建议先在对话中让 LLM 展示将要操作的对象再确认执行分页书签、标签、高亮、列表书签的列表类工具都支持 cursor 分页一次只返回一页默认 10 条需要完整遍历时应按返回的 cursor 连续调用自定义头如果你的实例在反向代理/网关后面务必通过KARAKEEP_CUSTOM_HEADERS传入代理要求的鉴权头否则 API 调用会被网关拦截。七、延伸阅读MCP 服务器的完整工具清单与 READMEapps/mcp/README.mdMCP 服务器源码apps/mcp/srcAPI Key 作用域定义packages/shared/types/apiKeys.tsAPI Key 创建界面apps/web/components/settings/AddApiKey.tsx服务端 API 路由packages/api/routesKarakeep 其他集成方式命令行、RSS、Agent 技能docs/docs/05-integrations【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考