yuna0x0-hackmd-mcp

HackMD MCP 服务

一个 Model Context Protocol（MCP）服务，可对接 HackMD API，让大模型客户端能够访问和操作 HackMD 笔记、团队、用户资料和历史记录。

功能

• 获取用户资料
• 创建、读取、更新和删除笔记
• 管理团队笔记并与团队成员协作
• 访问阅读历史
• 列出和管理团队
• 支持双传输方式：支持 HTTP 和 STDIO 传输
• 支持云端部署：支持 Smithery 等平台

要求

• Node.js 18+

本地安装（STDIO 传输）

1. 将此服务添加到你的 mcp.json / claude_desktop_config.json 中：

{
  "mcpServers": {
    "hackmd": {
      "command": "npx",
      "args": ["-y", "hackmd-mcp"],
      "env": {
        "HACKMD_API_TOKEN": "your_api_token"
      }
    }
  }
}

如果需要使用其他 HackMD API 端点，也可以选择设置 HACKMD_API_URL 环境变量。

2. 重启 MCP 客户端（例如 Claude Desktop）
3. 使用工具与 HackMD 交互

服务部署（HTTP 传输）

自托管

按照本地开发中的说明在本地设置项目，然后运行：

pnpm run start:http

此操作默认会在端口 8081 上启动服务。你可以通过设置 PORT 环境变量来更改端口。

云端部署

你可以将此 MCP 服务部署到任何支持 Node.js 服务端应用程序的云平台。

你也可以通过 Smithery 等 MCP 平台进行部署。

配置

环境变量（STDIO 传输，以及由主机提供配置的 HTTP 传输服务）

使用 STDIO 传输或托管 HTTP 传输服务时，可以通过环境变量传递配置：

• HACKMD_API_TOKEN：HackMD API 令牌（所有操作均必需）
• HACKMD_API_URL：（可选）HackMD API URL（默认为 https://api.hackmd.io/v1）

仅适用于 HTTP 传输服务的环境变量：

• ALLOWED_HACKMD_API_URLS：（可选）允许使用的 HackMD API URL 列表，以逗号分隔。如果提供的 HackMD API URL 不在此列表中，服务将拒绝请求。如果未设置，则仅允许默认 URL（https://api.hackmd.io/v1）。

注意

如果你托管的 HTTP 传输服务已预先配置令牌，则应保护你的端点，并在允许用户访问之前实现身份验证。否则，任何人都可以在使用你的 HackMD 令牌时访问 MCP 服务。

HTTP 标头（由用户提供配置的 HTTP 传输）

使用 HTTP 传输时，用户可以通过 HTTP 标头传递配置：

• Hackmd-Api-Token：HackMD API 令牌（所有操作均必需）
• Hackmd-Api-Url：（可选）HackMD API URL（默认为 https://api.hackmd.io/v1）

如果用户在标头中提供令牌，而服务也设置了 HACKMD_API_TOKEN，则优先使用标头中的值。

获取 HackMD API 令牌

要获取 API 令牌，请按以下步骤操作：

1. 前往 HackMD 设置。
2. 点击“Create API Token”。
3. 复制生成的令牌，并在 .env 文件或环境变量中使用。

可用工具

个人资料工具

• get_user_info：获取已验证用户的信息

团队工具

• list_teams：列出用户可访问的所有团队

历史记录工具

• get_history：获取用户的阅读历史

团队笔记工具

• list_team_notes：列出团队中的所有笔记
• create_team_note：在团队中创建新笔记
• update_team_note：更新团队中的现有笔记
• delete_team_note：删除团队中的笔记

用户笔记工具

• list_user_notes：列出用户拥有的所有笔记
• get_note：按 ID 获取笔记
• create_note：创建新笔记
• update_note：更新现有笔记
• delete_note：删除笔记

使用示例

基本笔记管理

Can you help me manage my HackMD notes?

列出笔记

Please list all my notes.

创建新笔记

Create a new note with the title "Meeting Notes" and content:
```
# Meeting Notes

Discussion points:
- Item 1
- Item 2
```

团队协作

Show me all the teams I'm part of and list the notes in the first team.

本地开发

本项目使用 pnpm 作为包管理器。

克隆仓库并安装依赖：

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

配置

1. 复制示例文件，创建 .env 文件：

cp env.example .env

2. 编辑 .env 文件并添加 HackMD API 令牌：

HACKMD_API_TOKEN=your_api_token

使用 MCP Inspector 调试

你可以使用 MCP Inspector 测试和调试 HackMD MCP 服务：

npx @modelcontextprotocol/inspector -e HACKMD_API_TOKEN=your_api_token npx hackmd-mcp

# Use this instead when Local Development
pnpm run inspector

然后在浏览器中打开提供的 URL（通常是 http://localhost:6274），访问 MCP Inspector 界面。在该界面中，你可以：

1. 连接到正在运行的 HackMD MCP 服务
2. 浏览可用工具
3. 使用自定义参数运行工具
4. 查看响应

在将其连接到 Claude Desktop 等 MCP 客户端之前，这对测试配置特别有用。

Docker

从 GitHub Container Registry 拉取：

docker pull ghcr.io/yuna0x0/hackmd-mcp

Docker 构建（本地开发）：

docker build -t ghcr.io/yuna0x0/hackmd-mcp .

Docker 多平台构建（本地开发）：

docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/yuna0x0/hackmd-mcp .

MCP Bundles（MCPB）

要为此服务创建 MCP Bundle，请运行：

pnpm run pack:mcpb

安全须知

此 MCP 服务会在 .env 文件、环境变量或 HTTP 标头中接收你的 HackMD API 令牌。请妥善保管此信息，切勿将其提交到版本控制中。

许可证

本项目采用 MIT License 授权；详情请参阅 LICENSE 文件。