hackmd-mcp 是一个 Model Context Protocol（MCP）服务器，用于将 HackMD 笔记平台与 AI 助手集成。它通过 HackMD API 让 LLM 客户端能够访问和操作 HackMD 的笔记、团队、用户资料以及历史数据。
主要能力
该服务器提供以下工具：
- 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：删除笔记
使用方式
本地安装（STDIO 传输）
将此服务器添加到 mcp.json / claude_desktop_config.json 中，可选设置 HACKMD_API_URL 环境变量以使用不同的 HackMD API 端点。重启 MCP 客户端（如 Claude Desktop）后即可使用工具与 HackMD 交互。
服务器部署（HTTP 传输）
按照本地开发说明在本地设置项目，然后运行服务器，默认端口为 8081，可通过 PORT 环境变量更改端口。
云部署
可将此 MCP 服务器部署到任何支持 Node.js 服务器应用的云平台，也可通过 Smithery 等 MCP 平台部署。
环境变量
STDIO 传输或托管 HTTP 传输服务器时，可通过环境变量传递配置：
- HACKMD_API_TOKEN：HackMD API Token（所有操作必需）
- HACKMD_API_URL：（可选）HackMD API URL，默认为 https://api.hackmd.io/v1
仅适用于 HTTP 传输服务器的环境变量：
- ALLOWED_HACKMD_API_URLS：（可选）允许的 HackMD API URL 逗号分隔列表。如果提供的 HackMD API URL 不在列表中，服务器将拒绝请求。如果未设置，仅允许默认 URL。
如果托管 HTTP 传输服务器并预配置了 token，应保护端点并在允许用户访问前实施身份验证，否则任何人都可以在使用你的 HackMD token 时访问你的 MCP 服务器。
HTTP 头（用户提供配置的 HTTP 传输）
使用 HTTP 传输时，用户可通过 HTTP 头传递配置：
- Hackmd-Api-Token：HackMD API Token（所有操作必需）
- Hackmd-Api-Url：（可选）HackMD API URL，默认为 https://api.hackmd.io/v1
如果用户在头中提供 token，而服务器也设置了 HACKMD_API_TOKEN，则头中的值优先。
获取 HackMD API Token
- 前往 HackMD 设置。
- 点击“Create API Token”。
- 复制生成的 token，并在 .env 文件或环境变量中使用。
适用场景
适用于需要将 HackMD 笔记平台与 AI 助手集成的场景，例如通过 LLM 客户端管理笔记、团队协作、访问阅读历史等。
限制
- 需要 HackMD API Token 才能进行所有操作。
- 使用 HTTP 传输时，如果服务器预配置了 token，需要自行实施身份验证以保护端点。
- 项目采用 MIT 许可证。
本地开发
项目使用 pnpm 作为包管理器。克隆仓库并安装依赖，复制示例创建 .env 文件，编辑 .env 文件并添加 HackMD API token。
可使用 MCP Inspector 测试和调试 HackMD MCP 服务器，打开浏览器访问提供的 URL（通常为 http://localhost:6274）即可访问 MCP Inspector 界面，连接服务器、浏览可用工具、使用自定义参数运行工具并查看响应。
Docker 相关：从 GitHub Container Registry 拉取，或进行本地开发构建、多平台构建。
MCP Bundles（MCPB）：运行命令创建 MCP Bundle。
安全提示
此 MCP 服务器接受 .env 文件、环境变量或 HTTP 头中的 HackMD API token。请确保信息安全，切勿提交到版本控制。
