Anytype (self-hosted HTTP)

ohneben Anytype MCP

通过自然语言与 Anytype 知识库对话，可使用 Claude、Cursor 等 AI 助手，以及任何其他 MCP 客户端。

这是官方 anyproto/anytype-mcp 的可自托管分支，新增了 Docker 容器和 Streamable-HTTP 传输方式，因此服务可在后台持续运行，并可通过 HTTP 供任何 MCP 客户端访问。（原版仅支持 stdio。）

为什么选择这个版本？

官方 Anytype MCP 服务 很出色，但它以 stdio 子进程的形式运行，每个客户端都必须按需启动它。本项目保留了全部功能，并新增了面向生产环境的部署方式：在 Docker 中运行一个常驻服务，供任意数量的 MCP 客户端通过 HTTP 访问。

功能	本项目	官方 anyproto/anytype-mcp	其他社区服务*
完整覆盖 Anytype API（动态 OpenAPI → MCP 工具）	✅	✅	✅
stdio 传输方式	✅	✅	✅
Streamable-HTTP 传输方式（原生支持或通过 mcp-remote）	✅	❌	❌
始终运行的后台服务	✅	❌	❌
一个服务 → 同时支持多个客户端	✅	❌	❌
Docker + docker-compose	✅	❌	❌
健康检查端点 + 自动重启	✅	❌	❌
端点的可选 bearer-token 身份验证	✅	❌	❌
🟢 / 🟡 / 🔴 只读 / 写入 / 破坏性工具提示	✅	➖	➖
自动化测试套件（Vitest）	✅	✅	➖
许可证	MIT	MIT	不一

_{*社区服务包括 Qwinty/anytype-mcp（JS）、wethegreenpeople/anytype-mcp（Python）和 anytype-mcp-plus——大多数仅支持 stdio，并通过 npx 启动。“➖” = 未说明 / 情况不一。数据截至 2026 年 7 月；请查看各项目以获取最新信息。}

简而言之：如果你只想通过 AI 客户端试用 Anytype，官方服务就很合适。如果你想让它在后台运行、随时待命，并供你机器上的所有 MCP 客户端共享，就使用这个版本。

你可以做什么

连接后，你可以向助手询问这类问题：

• “在我的 Anytype 中搜索有关 Q3 发布的笔记。”
• “创建一个任务‘撰写报告’，截止日期为 3 天后。”
• “新建一个名为‘旅行’的空间，并添加一份打包清单。”

工具会根据正在运行的 Anytype 应用自动生成，并分为 🟢 只读、🟡 写入和 🔴 删除三类。

此服务经过优化，可减少工具调用，让助手运行更快速、更节省资源：

• API-get-overview — 一个综合工具，可通过一次调用返回所有空间及其类型；也可以提供 space_id，以获取该空间的类型和属性定义。这样就不必依次调用列出空间 → 列出类型 → 列出属性。
• 精简响应 — API 负载在传递给助手前会经过压缩：空属性值、object 判别字段和 null 值会被移除，每个搜索或列表结果中嵌入的类型也会精简为标识符。通常，这会让列表和搜索响应缩小一半以上，从而减少每次调用消耗的上下文，并减少后续调用次数。设置 ANYTYPE_MCP_SLIM_RESPONSES=false 可获取原始 API 负载。
• 路由提示 — 工具描述会告知助手哪种工具最适合以较低成本完成任务（例如，搜索比对列表分页更合适；只有 get-object 会返回完整的 markdown 正文）。

工作原理

Claude / Cursor / …  ──MCP──►  this server  ──HTTP──►  Anytype desktop app (local API)

此服务只与本机 Anytype 桌面应用的本地 API通信。你的数据会保留在自己的电脑上。

要求

• 已安装并正在运行的 Anytype 桌面应用（它会在 127.0.0.1:31009 提供本地 API）。
• 按照以下步骤进行配置需要 Docker（macOS/Windows 上使用 Docker Desktop）。

快速开始（Docker）

1. 添加 API 密钥。 复制示例配置并粘贴密钥：

cp .env.example .env
# open .env and set ANYTYPE_API_KEY=...   (see "Get an API key" below)

2. 启动服务：

docker compose up -d --build

3. 确认服务正在运行：

curl -s http://localhost:8769/healthz     # → {"status":"ok"}

4. 连接 MCP 客户端。 在 mcpServers 下添加一个 anytype 条目，然后完全退出并重新打开应用。选择与你的客户端相符的配置：

Claude Code（或任何原生支持 Streamable-HTTP 的客户端）— 直接连接，无需辅助进程：

"anytype": {
  "type": "http",
  "url": "http://localhost:8769/mcp"
}

Claude Desktop（其配置仅支持 stdio）需要使用 mcp-remote 桥接程序。安装一次，然后通过 node 而非 npx 启动：

npm i -g mcp-remote

"anytype": {
  "command": "/opt/homebrew/bin/node",
  "args": [
    "/opt/homebrew/lib/node_modules/mcp-remote/dist/proxy.js",
    "http://localhost:8769/mcp",
    "--allow-http"
  ]
}

为什么不用 npx -y mcp-remote …？ 每次启动时，npx 都会通过 npm 缓存重新解析软件包。客户端同时冷启动多个 MCP 服务时，它们会争用该缓存， 某些启动器可能会在 npx 内部卡住好几分钟，导致客户端报告连接超时。一次性安装 mcp-remote 并通过 node 启动，就能省去这一步。请使用绝对路径（图形界面应用不会继承 shell 的 PATH，而且 mcp-remote 自带的 #!/usr/bin/env node shebang 也无法以其他方式找到 node）。上面的路径是 Apple Silicon 版 Homebrew 的默认路径； 如果你的路径不同，请使用 which node 和 npm root -g 进行调整。

就这么简单——让助手在 Anytype 中搜索或创建内容即可。

获取 API 密钥

在 Anytype 桌面应用中：设置 → API 密钥 → 创建新密钥。将密钥复制到 .env 中的 ANYTYPE_API_KEY=。密钥会保留在 .env 中，而 git 会忽略该文件， 因此密钥不会被提交。

配置

所有配置都在 .env 中（从 .env.example 复制而来）：

变量	默认值	作用
ANYTYPE_API_KEY	—	你的 Anytype API 密钥。必填。
ANYTYPE_VERSION	2025-11-08	Anytype API 版本标头。
ANYTYPE_API_BASE_URL	http://host.docker.internal:31009	容器访问 Anytype 应用 API 的地址。
ANYTYPE_API_HOST_HEADER	（自动）	发送到 Anytype API 的 Host 标头。当基础 URL 使用容器主机别名时，会自动设为 localhost:<port>，因为 Anytype 会拒绝其他任何 Host，并返回 403 request origin is not allowed。
PORT	8769	MCP 端点的主机端口。
MCP_SHARED_TOKEN	（空）	用于保护端点的可选 bearer token。留空 = 不设保护，仅限 localhost 使用。
ANYTYPE_MCP_SLIM_RESPONSES	true	在将 API 响应发送给助手之前进行精简。设为 false 可获取原始负载。

更改 .env 后，运行 docker compose up -d --force-recreate 重新加载。

有关日志、重启、密钥轮换和验证命令，请参阅 DOCKER.md。

从源代码运行（stdio，无需 Docker）

更喜欢经典的 stdio 模式？在本地构建：

npm install
npm run build

然后使用 stdio 命令和 OPENAPI_MCP_HEADERS 中的密钥向客户端注册；确切的 stdio 配置请参阅上游 README。

安全

• 你的 API 密钥仅保存在 .env 中，该文件已被 git 忽略。切勿提交真实密钥。
• HTTP 端点默认无需身份验证（在 localhost 上使用没有问题）。如需在本机之外公开访问， 请设置 MCP_SHARED_TOKEN，并通过 Bearer 标头或 ?token=… 发送该令牌。

MCP Registry

此服务以 io.github.ohneben/anytype-mcp 这一名称发布到官方 MCP Registry。查询当前条目：

curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.ohneben/anytype-mcp"

其条目由 server.json 描述，并在每个 v*.*.* 标签上通过 .github/workflows/publish-mcp.yml 自动重新发布。 该工作流会等待匹配的 GHCR 镜像，并使用 GitHub OIDC 进行身份验证（无需密钥）。 Registry 通过 Dockerfile 中的 io.modelcontextprotocol.server.name 标签验证镜像归属，因此 GHCR 软件包必须保持公开。

发布

Git 标签就是版本。 推送 v1.2.3 即完成整个发布流程：构建镜像前，标签会写入 package.json；发布条目前，标签会写入 server.json。因此，服务向 MCP 客户端报告的版本、镜像标签和 Registry 条目不会互相冲突。无需事先手动 更新版本号，这里提交的版本仅作为本地构建使用的默认值。

致谢与许可证

基于 Any Association 的官方 Anytype MCP 服务构建。 根据 MIT License 授权。