项目简介

Roam Research MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务，它将 AI 助手（如 Claude Desktop）与您的 Roam Research 知识图谱连接起来。通过这个服务器，AI 助手可以直接访问、搜索、创建和修改您的 Roam Research 数据，极大地扩展了 AI 在个人知识管理领域的应用能力。

主要功能点

• 内容创建: 创建新页面、添加子块、构建层级大纲、导入Markdown内容、添加待办事项、更新现有内容。
• 搜索与检索: 根据文本、标签、TODO/DONE状态、块引用、层级关系或日期搜索内容；查找最近修改的页面；执行高级Datalog查询。
• 记忆系统: 允许AI存储跨会话记忆，并支持按类别过滤和按日期排序的回忆检索。
• 外部内容处理: 自动从网页、PDF文档中提取主要内容，并获取YouTube视频的文字转录。

安装步骤

本项目通常不需要独立安装，而是通过 MCP 客户端（如 Claude Desktop）的配置来自动管理和运行。

1. 安装 MCP 客户端: 例如，下载并安装 Claude Desktop (https://claude.ai/download)。
2. 获取 Roam Research API Token 和图谱名称: 登录您的 Roam Research 图谱，进入 'Settings' -> 'API tokens'，生成新的 API Token 并复制。记录您的图谱名称（即 Roam URL 中 'https://roamresearch.com/#/app/' 后面的部分）。
3. 配置 MCP 客户端: 编辑您的 MCP 客户端配置文件，添加此 Roam MCP 服务器的配置信息。

服务器配置 (MCP 客户端配置)

您需要在 MCP 客户端的配置文件中添加一段 JSON 配置，告诉客户端如何启动和连接到 Roam MCP 服务器。配置信息包括服务器名称、启动命令、参数以及 Roam Research API 凭证作为环境变量。

• 配置文件路径示例:

  • Mac: '~/Library/Application Support/Claude/claude_desktop_config.json'
  • Windows: '%APPDATA%\Claude\claude_desktop_config.json'

• 配置内容说明:

  • 'mcpServers': 包含所有 MCP 服务器配置的对象。
  • 'roam-helper': 您给这个服务器实例定义的名称，可以在客户端中引用。
  • 'command': 客户端用于启动服务器进程的命令。通常使用 'uvx'（一个轻量级 Python 虚拟环境执行器）来通过 Git URL 直接运行项目，或者使用 'python' 命令加上服务器主文件的路径（如果您将项目克隆到本地）。
  • 'args': 传递给启动命令的参数。如果使用 'uvx'，参数就是项目的 Git URL。如果使用本地 Python，参数就是服务器入口文件（如 'roam_mcp/cli.py'）的路径，可能还需要指定传输协议（如 '--transport stdio'）。
  • 'env': 一个包含环境变量的 JSON 对象。必须包含 'ROAM_API_TOKEN' 和 'ROAM_GRAPH_NAME'，其值分别设置为您的 Roam Research API Token 和图谱名称。可选的 'MEMORIES_TAG' 可以用来指定AI记忆存储的标签。

  请根据您的客户端类型和安装方式（例如是否使用 uvx）填写 'command' 和 'args' 的具体值。

基本使用方法

配置完成后，启动您的 MCP 客户端。AI 助手应该会自动检测并连接到 Roam Research MCP Server。

现在，您可以直接与 AI 助手对话，并要求它执行与 Roam Research 相关的任务，无需编写代码。AI 会自动调用 Roam MCP Server 提供的相应工具。

• 示例对话:
  • “将这些会议纪要添加到我在 Roam 今天的每日笔记中。”
  • “在我的 Roam 图谱中搜索所有标记有 #ProjectIdeas 的块。”
  • “在 Roam 中创建一个名为 ‘项目计划’ 的新页面。”
  • “提取这个网页的主要内容并添加到我的 Roam 图谱。”
  • “记下我需要在下周完成这个任务。” (使用记忆系统)