Anytype MCP Server

Anytype MCP 服务

Anytype MCP 服务是一个 Model Context Protocol (MCP) 服务，可让 AI 助手通过自然语言与 Anytype 的 API 无缝交互。

它将 Anytype 的 OpenAPI 规范转换为 MCP 工具，弥合了 AI 与 Anytype 强大功能之间的鸿沟，让你可以通过对话管理知识库。

功能

• 全局搜索和空间搜索
• 空间和成员
• 对象和列表
• 属性和标签
• 类型和模板

快速开始

1. 获取 API 密钥

1. 打开 Anytype
2. 前往应用设置
3. 转到 API 密钥部分
4. 点击 Create new 按钮

npx -y @anyproto/anytype-mcp get-key

2. 配置 MCP 客户端

Claude Desktop、Cursor、Windsurf、Raycast 等

将 <YOUR_API_KEY> 替换为你的实际 API 密钥后，将以下配置添加到 MCP 客户端设置中：

{
  "mcpServers": {
    "anytype": {
      "command": "npx",
      "args": ["-y", "@anyproto/anytype-mcp"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <YOUR_API_KEY>\", \"Anytype-Version\":\"2025-11-08\"}"
      }
    }
  }
}

提示： 在 Anytype 中创建 API 密钥后，你可以在 API 密钥部分复制已填入 API 密钥、可直接使用的配置片段。

Claude Code (CLI)

将 <YOUR_API_KEY> 替换为你的实际 API 密钥后，运行此命令添加 Anytype MCP 服务：

claude mcp add anytype -e OPENAPI_MCP_HEADERS='{"Authorization":"Bearer <YOUR_API_KEY>", "Anytype-Version":"2025-11-08"}' -s user -- npx -y @anyproto/anytype-mcp

npm install -g @anyproto/anytype-mcp

{
  "mcpServers": {
    "anytype": {
      "command": "anytype-mcp",
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <YOUR_API_KEY>\", \"Anytype-Version\":\"2025-11-08\"}"
      }
    }
  }
}

自定义 API 基础 URL

默认情况下，服务连接到 http://127.0.0.1:31009。对于 anytype-cli（端口 31012）或其他自定义基础 URL，请设置 ANYTYPE_API_BASE_URL：

{
  "mcpServers": {
    "anytype": {
      "command": "npx",
      "args": ["-y", "@anyproto/anytype-mcp"],
      "env": {
        "ANYTYPE_API_BASE_URL": "http://localhost:31012",
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <YOUR_API_KEY>\", \"Anytype-Version\":\"2025-11-08\"}"
      }
    }
  }
}

claude mcp add anytype \
  -e ANYTYPE_API_BASE_URL='http://localhost:31012' \
  -e OPENAPI_MCP_HEADERS='{"Authorization":"Bearer <YOUR_API_KEY>", "Anytype-Version":"2025-11-08"}' \
  -s user -- npx -y @anyproto/anytype-mcp

交互示例

以下是一些与你的 Anytype 交互的示例：

• “创建一个名为 ‘Project Ideas’、描述为 ‘A space for storing project ideas’ 的新空间”
• “在 ‘Project Ideas’ 空间中创建一个类型为 ‘Task’、标题为 ‘Research AI trends’ 的新对象”
• “再创建一个，标题为 ‘Dive deep into LLMs’，截止日期设为 3 天后，并分配给我”
• “现在创建一个标题为 ‘Tasks for this week’ 的集合，并将这两个任务添加到该列表中。将第一个任务的截止日期设为 10 天后”

工具行为和 API 版本

服务会在启动时加载一份 OpenAPI 文档。使用标准配置时，它会先尝试 /v2/docs/openapi.json。如果该端点返回 404 或 410，则会回退到同一服务上的 /docs/openapi.json，旧版应用会在此提供 v1 API。这样，在 v2 可用时会优先选择 v2，同时也支持仅提供旧版 API 的应用：

"args": ["-y", "@anyproto/anytype-mcp"]

若要明确使用旧版 v1 API，请选择其版本化规范：

"args": ["-y", "@anyproto/anytype-mcp", "run", "http://127.0.0.1:31009/v1/docs/openapi.json"]

版本化 URL /v2/docs/openapi.json 仍可用于明确选择 v2。

显式指定的规范 URL 和本地文件会按原样使用，不会触发回退。身份验证失败、服务端错误、连接失败以及格式错误的 JSON 也会导致启动失败，而不会改用其他 API。封装器会使用所选文档中声明的路由，不会重写其版本前缀。

每个 MCP 进程只执行一次发现。工具调用会复用已解析的规范和 HTTP 客户端，不会再次获取 OpenAPI。更新 Anytype 后，请重启 MCP 服务以发现新提供的 API 版本；不会使用持久化的规范缓存。

工具描述中包含操作指南；调用失败时会返回 API 错误，其中包括 isError: true、可用时的 HTTP 状态码，以及 API 的代码、消息、问题和提示。

服务在其提供的说明文字中，会使用 OpenAPI operationId 命名自身操作。在 MCP 工具列表以及 get_schema 或 get_op_schema 响应的字段描述中，这些名称会改写为此封装器的工具名称（list_properties 会变为 API-list-properties）。修复提示则有所不同：服务会将其提及的每个操作写成 REST 路由，并将其列为带类型的 see_also 引用，因此封装器会将该路由文本替换为工具名称和参数，并为该引用添加 tool 和 args。字面值绝不会被改写：枚举值和示例值、op 名称、endpoint 字符串以及输出架构都会保留服务端的写法；OpenAI 和 Anthropic 工具导出也一样，它们使用 operationId 命名工具。

成功的 v1 对象创建、更新、删除和聊天创建操作，会返回精简的 object 回执，其中包含 ID、空间 ID、名称、归档状态，以及可用时的类型标识。封装器会省略回显的 Markdown、片段、属性值、图标和完整类型定义。警告、生成的 ID 以及 etag／重试元数据会予以保留。需要时，请读取对象以获取其内容。v2 已会返回精简的创建／编辑回执，封装器会原样传递，但会重新拼写警告中的提示，并为引用添加 tool 和 args；读取、搜索和错误也会保留完整的 API 响应。

共享的工具策略会控制输入和请求路由：

• Authorization 和 Anytype-Version 来自 OPENAPI_MCP_HEADERS。
• expected_etag 映射到 If-Match。使用先前读取时获得的 etag，可防止覆盖已更改的对象。包装器不会重试前置条件失败，也不会移除该条件。若有响应 etag，会在单独的 request_metadata 文本块中返回。
• request_key 会在声明了该请求头的端点上映射到 Idempotency-Key。新写入时请省略此参数；包装器会生成唯一键，并在 request_metadata 或错误的 request_key 中返回。仅在重试同一写入时复用。不同调用会生成不同的键，即使文档完全相同也如此。不会自动重试。在 OPENAPI_MCP_HEADERS 中设置全局 Idempotency-Key 会被拒绝。
• 现有调用方仍可使用准确的旧版 If-Match 和 Idempotency-Key 参数名称。文档不会同时列出新旧名称。若别名值冲突，则会被拒绝。
• 分页、字段选择、dry_run、create_missing_options 和架构发现仍可用。
• 配对和 API 密钥管理不在支持范围内。v2 auth_whoami 仍可用于查看当前凭据的权限；其响应不包含 bearer token。
• 事件流工具不在支持范围内，因为它们无法生成有界的工具结果。请使用消息列表工具检索聊天消息。
• 支持通过二进制适配器下载文件。该工具会将字节流式传输到私有临时目录，并返回 path、filename、media_type 和 size。该路径位于运行 MCP 的机器/容器上。成功下载的文件会保留在该目录中，直到被移除或由操作系统清理；中断的下载会被移除。范围和缓存请求头不会作为模型输入。

具有 HTTP 含义的已知输入会按参数位置匹配，因此文档自身的字段会保留。开放式 JSON 文档使用 body 参数。具有已声明字段的对象使用扁平参数。现有的扁平化 filters 字段缺失问题，以及 FilterExpression 架构回退仍是独立限制；此次清理不会恢复对筛选器架构的支持。

重复的最终工具名称会导致启动失败，并同时指出对应路由。请分别选择 v1/v2 规范，而不是合并名称重叠的操作。

设置 ANYTYPE_MCP_DEBUG=1，可在 stderr 上输出简洁的操作名称、响应状态和耗时。不会记录参数、授权请求头、载荷或完整操作表。

测量工具定义

bun run measure-tools
# Or inspect a different local OpenAPI document:
bun run measure-tools ./path/to/openapi.json

默认命令会比较固定的 v1 和 v2 样例。它会报告工具数量、序列化字符数和 UTF-8 字节数，而不是特定于模型的 token 数量。

开发

从源代码安装

1. 克隆仓库：

git clone https://github.com/anyproto/anytype-mcp.git
cd anytype-mcp

2. 安装依赖（需要 Bun）：

bun install

3. 构建项目：

bun run build

4. 全局链接该包（可选）：

bun link

贡献

感谢你愿意与我们一起开发 Anytype！

❤️ 本项目及所有参与者均受行为准则约束。

🧑‍💻 请查看我们的贡献指南，了解如何提问、创建问题或提交拉取请求。

🫢 如发现安全问题，请发送邮件至 [email protected]，并参阅我们的安全指南了解更多信息。

🤝 在 Github 上关注我们，并加入贡献者社区。

由 Any 制作——一个瑞士协会 🇨🇭

基于 MIT 许可。