HackMD MCP Server 使用说明

项目简介

HackMD MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，专门为 HackMD 用户设计。它允许 AI 助手（如 Claude）安全地访问和操作您的 HackMD 笔记，实现知识库的智能化管理。通过此服务器，您可以让 AI 助手执行例如创建、读取、更新、删除笔记，以及查看阅读历史和团队笔记等操作，极大地提升了 AI 助手与个人知识库的互动能力。

主要功能点

用户信息获取: 获取当前 HackMD 用户的个人信息。
笔记管理: 支持对个人 HackMD 笔记的增删改查 (CRUD) 操作，包括创建、读取、更新和删除笔记。
历史记录查询: 查看用户的 HackMD 阅读历史记录。
团队协作支持: 列出用户所属的团队，并能查看团队内的笔记列表，方便团队知识管理。
灵活的权限控制: 在创建和更新笔记时，可以设置阅读和写入权限（owner, signed_in, guest）。

安装步骤

克隆仓库: 首先，将仓库代码克隆到本地：

git clone https://github.com/yuna0x0/hackmd-mcp.git
cd hackmd-mcp

安装依赖: 确保您已安装 Bun (或 Node.js 18+)。然后使用 Bun 安装项目依赖：
```
bun install
```
配置 API Token: 您需要从 HackMD 设置获取 API Token。
- 方法一：使用 .env 文件 (推荐): 复制 '.env.example' 文件并重命名为 '.env'，然后编辑 '.env' 文件，填入您的 HackMD API Token：
```
cp .env.example .env
vim .env  # 或您喜欢的编辑器
```
  在 '.env' 文件中添加：
```
HACKMD_API_TOKEN=your_api_token_here
```
- 方法二：使用环境变量: 您也可以在启动服务器时直接通过环境变量提供 API Token。

服务器配置

为了让 MCP 客户端（如 Claude Desktop）连接到 HackMD MCP Server，您需要在客户端的配置文件中添加服务器信息。以 'claude_desktop_config.json' 为例，您需要配置 'mcpServers' 部分，添加一个名为 'hackmd' 的服务器配置。

{
  "mcpServers": {
    "hackmd": {
      "command": "bun",  // 启动服务器的命令，这里使用 bun
      "args": ["start"]   // 启动命令的参数，这里 "start" 对应 package.json 中的启动脚本
    }
  }
}

配置说明:

'server name': 'hackmd' (服务器名称，客户端用此名称引用)
'command': 'bun' (或您系统中启动 Bun 的命令)
'args': '["start"]' (启动服务器的参数，根据 'package.json' 中的 scripts 配置，'start' 命令通常用于启动开发服务器)

如果您选择使用环境变量方式配置 API Token，并且 hackmd-mcp 仓库位于 '/path/to/hackmd-mcp'，则 'claude_desktop_config.json' 的配置可能如下所示:

{
  "mcpServers": {
    "hackmd": {
      "command": "bash",  // 使用 bash 执行命令
      "args": ["-c", "HACKMD_API_TOKEN=your_token_here bun run /path/to/hackmd-mcp/index.ts"] // 通过 bash 设置环境变量并启动服务器
    }
  }
}

配置说明:

'server name': 'hackmd'
'command': 'bash' (或您系统中执行 bash 脚本的命令)
'args': '["-c", "HACKMD_API_TOKEN=your_token_here bun run /path/to/hackmd-mcp/index.ts"]' (使用 bash 的 '-c' 参数执行一段命令，该命令首先设置环境变量 'HACKMD_API_TOKEN'，然后使用 bun 运行 'index.ts' 文件。请将 '/path/to/hackmd-mcp/index.ts' 替换为 'index.ts' 文件的实际路径。)

请注意: '/path/to/hackmd-mcp/index.ts' 需要替换为 'index.ts' 文件在您本地文件系统中的绝对路径。为了简化配置，推荐使用 '.env' 文件配置 'HACKMD_API_TOKEN'，并使用第一种配置方式，将当前工作目录切换到 'hackmd-mcp' 仓库根目录。

基本使用方法

启动服务器: 在 'hackmd-mcp' 仓库目录下，运行以下命令启动 MCP 服务器：
```
bun start
```
或者，如果您使用 bunx 且通过环境变量提供 API Token，可以运行：
```
HACKMD_API_TOKEN=your_token_here bunx hackmd-mcp
```
连接 MCP 客户端: 配置您的 MCP 客户端（如 Claude Desktop），使其连接到 HackMD MCP Server。具体的连接方式请参考 MCP 客户端的文档。通常您需要在客户端中配置服务器的启动命令和参数，如上述 'claude_desktop_config.json' 示例所示。
使用工具: 在 MCP 客户端中，您应该能看到 HackMD MCP Server 提供的工具列表，例如 'get_user_info', 'list_user_notes', 'create_note' 等。您可以指示 AI 助手使用这些工具来操作您的 HackMD 笔记。例如，在 Claude 中，您可以说：
```
请列出我的所有 HackMD 笔记。
```
Claude 可能会调用 'list_user_notes' 工具并将结果返回给您。

安全提示

请妥善保管您的 HackMD API Token，避免泄露。不要将 API Token 提交到版本控制系统。

关键词