mdFiles MCP Server

mdFiles 文档管理系统的 Model Context Protocol (MCP) Server，使 Claude Code、Cursor 等 AI 工具可以原生集成读写 mdFiles 中的文档。

功能

• 浏览项目空间、文件夹和文件树
• 读取文件最新内容（草稿版本）
• 创建和更新 Markdown 文件
• 为单个文件生成受控分享链接
• 增量更新文件章节（替换、追加、前置、追加到节）
• 搜索文档（按关键词、标签、空间过滤）

安装

本地开发

cd mdFiles-mcp
npm install
npm run build

通过 npx 运行（无需安装）

MDFILES_API_URL=https://your-domain.com MDFILES_API_KEY=mdf_xxx npx mdfiles-mcp

全局安装

npm install -g mdfiles-mcp

配置

通过环境变量配置：

| 环境变量 | 说明 | 示例 | |---------|------|------| | MDFILES_API_URL | mdFiles 后端 API 地址，需包含后端 context path | https://api-mdf.kuaidianhao.com/api/v1 | | MDFILES_API_KEY | 开放 API Key | mdf_A3kR9mXpQzLvBn7cYeWd2TsUfGhIoJa |

注意：不要填写前端站点地址（例如 https://mdf.kuaidianhao.com）。MCP 需要访问后端开放接口，完整请求会拼接为 ${MDFILES_API_URL}/open/v1/...。

API Key 由系统管理员在 mdFiles 后台创建，需具备相应 Scope 权限。

AI 工具配置

Claude Code

在 ~/.claude/settings.json 或项目 .claude/settings.local.json 中添加：

{
  "mcpServers": {
    "mdfiles": {
      "command": "node",
      "args": ["/absolute/path/to/mdFiles-mcp/dist/index.js"],
      "env": {
        "MDFILES_API_URL": "https://api-mdf.kuaidianhao.com/api/v1",
        "MDFILES_API_KEY": "mdf_xxxxxxxx"
      }
    }
  }
}

Cursor

在 Cursor Settings -> Features -> MCP Servers 中添加：

• Type: stdio
• Command: node /absolute/path/to/mdFiles-mcp/dist/index.js
• Environment Variables:
  • MDFILES_API_URL=https://api-mdf.kuaidianhao.com/api/v1
  • MDFILES_API_KEY=mdf_xxxxxxxx

Codex

在 ~/.codex/config.toml 中添加：

[mcp_servers.mdfiles]
type = "stdio"
command = "npx"
args = ["-y", "mdfiles-mcp"]
env = { MDFILES_API_URL = "https://api-mdf.kuaidianhao.com/api/v1", MDFILES_API_KEY = "mdf_xxxxxxxx" }

如果使用本地构建版本，也可以把 command 和 args 改为：

command = "node"
args = ["/absolute/path/to/mdFiles-mcp/dist/index.js"]

Claude Desktop

在配置文件中添加（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "mdfiles": {
      "command": "node",
      "args": ["/absolute/path/to/mdFiles-mcp/dist/index.js"],
      "env": {
        "MDFILES_API_URL": "https://api-mdf.kuaidianhao.com/api/v1",
        "MDFILES_API_KEY": "mdf_xxxxxxxx"
      }
    }
  }
}

可用 Tools

| Tool | 描述 | 参数 | |------|------|------| | list_spaces | 列出所有可访问的项目空间 | 无 | | list_folders | 列出指定空间下的文件夹树形结构 | spaceId: string | | list_files | 列出指定文件夹下的文件 | folderId: string | | read_file | 读取文件的最新内容（草稿版本） | fileId: string | | write_file | 更新文件内容（自动创建新版本） | fileId: string, content: string, description?: string | | create_file | 在指定文件夹中创建新的 Markdown 文件 | folderId: string, name: string, content: string | | create-share-link | 为单个文件创建受控分享链接 | fileId: string, expireDays?: number, password?: string | | patch_section | 增量更新文件的指定章节 | fileId: string, mode: string, content: string, sectionHeading?: string | | search_docs | 搜索文档 | keyword?: string, tagId?: string, spaceId?: string |

patch_section 模式说明

• replace_section：替换指定章节的完整内容（需提供 sectionHeading）
• append：在文件末尾追加内容
• prepend：在文件开头插入内容
• append_to_section：追加到指定章节末尾（需提供 sectionHeading）

使用示例

列出所有空间：

> 请列出我可以访问的项目空间

读取文件：

> 读取文件 ID 为 9876543210 的内容

更新文件：

> 将文件 9876543210 的内容更新为 "# 新标题\n\n这是新内容"

创建文件：

> 在文件夹 444555666 中创建一个名为 "需求文档.md" 的文件，内容是 "# 需求概述"

搜索文档：

> 搜索包含 "API 设计" 的文档

本地回退查询

如果 Codex/Claude 等客户端的 MCP 调用被上游模型网关或审批链路拦住，可以在仓库根目录直接运行只读查询脚本：

MDFILES_API_URL=https://api-mdf.kuaidianhao.com/api/v1 \
MDFILES_API_KEY=mdf_xxxxxxxx \
node scripts/list-space-docs.mjs "纸条屋" "需求目标"

默认第二个参数是 需求目标，不传时会自动查询该文件夹；如果文件夹不存在，脚本会列出空间下可用文件夹。

技术栈

• TypeScript 5.x
• Node.js 18+ (原生 fetch)
• @modelcontextprotocol/sdk

后端接口

MCP Server 本质上是 mdFiles 后端 /open/v1 开放接口的客户端封装。详见后端 OPEN-API-GUIDE.md。

License

MIT