md MCP

md-mcp

从即时工程到情境工程的转变。

一个轻量级的Python库，可以立即将您的本地markdown文档、注释和知识库公开给 任何 支持模型上下文协议（MCP）的AI工具，包括Claude Desktop。

无嵌入、无预处理、无上传。您的文件安全地保存在本地计算机上，任何实时更新都会立即反映在您的AI上下文中。

______________________________________________________________________

🚀 快速开始

1.安装

选项A：从pypi安装

pip install md-mcp

选项B：从源代码安装

pip install -e .

2.启动Web UI（推荐）

管理markdown服务器的最简单方法是通过可视化仪表板：

md-mcp --web

*只需指向一个文件夹即可！*

3.或使用CLI

如果您更喜欢命令行：

# Expose a folder of markdown files
md-mcp --folder ~/Documents/notes --name "My Notes"

# That's it! Restart Claude Desktop and it's available.

______________________________________________________________________

📋 特性

• 语境工程：为你的人工智能助手提供准确的本地上下文，以获得更好的答案，从而消除了无休止地提示的需要。
• 通用MCP支持：与Claude Desktop和支持模型上下文协议的任何其他AI工具或代理本机配合使用。
• 本地和安全第一：你的文件永远不会离开你的机器。没有云上传，没有第三方API解析您的敏感笔记。
• 实时同步：编辑您的markdown文件，MCP服务器会立即获取更改。无需重新生成嵌入或重新索引。
• 自动文件监视：自动检测何时添加、修改或删除文件（由 看门狗).使用 rescan_folder() Claude Desktop中的工具，如有需要，可手动刷新。
• 零配置：只需指向一个文件夹即可。
• 自动发现：递归查找所有 .md 文件夹。
• 元数据抽取：解析YAML frontmatter和第一段，以获取丰富的资源描述。
• 搜索支持：在所有文件中内置搜索功能，可以快速找到大海捞针。
• 网络界面：易于使用的可视化仪表板，供非技术用户管理多个知识库。

______________________________________________________________________

🎯 用例

1.个人知识库

md-mcp --folder ~/obsidian-vault --name "Obsidian"

→ 克劳德现在可以读取你的整个黑曜石金库了

2.项目文件

md-mcp --folder ~/code/myproject/docs --name "Project Docs"

→ 克劳德对你的项目了如指掌

3.研究论文

md-mcp --folder ~/research/papers-md --name "Research"

→ 克劳德可以参考你的研究笔记

______________________________________________________________________

📖 高级用法命令

Web界面（最简单的使用方法）

md-mcp --web
# Launches a dashboard to manage all your markdown servers

# You can optionally specify a custom port (default is 5000)
md-mcp --web --port 8080

添加Markdown文件夹

# With explicit name
md-mcp --folder /path/to/docs --name "My Docs"

# Auto-name from folder
md-mcp --folder ~/notes
# Creates server named "notes"

# Alias: --add
md-mcp --add ~/work-docs --name "Work"

添加前扫描（干运行）

md-mcp --folder ~/notes --scan
# Shows what files would be exposed

列出已配置的服务器

md-mcp --list
# Shows all md-mcp servers

显示配置状态

md-mcp --status
# Shows Claude config path and all servers

删除服务器

md-mcp --remove "My Docs"

交互模式

md-mcp
# Prompts for folder path

______________________________________________________________________

🔧 运作原理

1. 您运行CLI：

   md-mcp --folder ~/notes --name "Notes"

1. md-mcp：

- 扫描文件夹以查找 .md 文件 - 提取元数据（封面、描述） - 更新Claude桌面配置 - 注册MCP服务器条目

1. 在克劳德桌面中：

- 重新启动克劳德 - 服务器出现在MCP下拉列表中 - 所有可用作资源的markdown文件 - 使用搜索工具查找内容

______________________________________________________________________

📂 暴露了什么

每个markdown文件都变成一个 MCP资源:

{
  "uri": "md://notes/project-plan.md",
  "name": "Project Plan",
  "description": "Auto-extracted from frontmatter or first paragraph",
  "mimeType": "text/markdown"
}

______________________________________________________________________

🛠️ MCP工具

md-mcp为Claude提供了三个工具：

1. search_markdown

按内容或文件名搜索所有markdown文件。

Claude中的用法：

• 标准（关键字）： >“在我的笔记中搜索‘docker compose’”

⚠️ 以下实验功能：（可能不起作用）

• 语义的： >“使用语义搜索在我的文档中搜索‘用户身份验证’” *（查找登录、OAuth等相关概念）*
• 混合的： >“使用混合搜索搜索'docker setup'” *（结合精确匹配和概念匹配）*

*（注：语义和混合搜索需要 pip install md-mcp[semantic])*

2. list_files

列出所有可用的markdown文件。

Claude中的用法：

“我有什么关于Python的markdown文件？”

3. rescan_folder

手动重新扫描文件夹以查找新的、修改的或删除的markdown文件。如果自动文件监视器不可用或文件丢失，请使用此选项。

Claude中的用法：

“重新扫描markdown文件夹以查找我的新笔记”

______________________________________________________________________

📋 需求

• Python 3.10+
• 主控程序 图书馆
• 克劳德桌面版

______________________________________________________________________

🔧 配置

Claude桌面配置位置（自动）

窗户： %APPDATA%\Claude\claude_desktop_config.json

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

Linux： ~/.config/Claude/claude_desktop_config.json

反重力配置位置（手动）

窗户： %USERPROFILE%\.gemini\antigravity\mcp_config.json

添加配置并运行 开发者：重新加载窗口 从命令选项板(Ctrl+Shift+P).

配置条目格式

{
  "mcpServers": {
    "my-notes": {
      "command": "C:\\Python\\python.exe",
      "args": [
        "-m", "md_mcp.server_runner",
        "--folder", "C:\\Users\\Yang\\notes",
        "--name", "my-notes"
      ]
    }
  }
}

VS代码MCP配置（手动）

对于工作空间级工具，请使用以下文件 .vscode/mcp.json。参见 官方VS Code MCP文档.

\[！重要\] 对于工作区配置，顶级密钥为 "servers", 不 "mcpServers".

示例 .vscode/mcp.json:

{
  "servers": {
    "my-notes": {
      "command": "C:\\Python\\python.exe",
      "args": [
        "-m", "md_mcp.server_runner",
        "--folder", "C:\\Users\\Yang\\notes",
        "--name", "my-notes"
      ]
    }
  }
}

样品测试提示

配置后，请使用您的AI助手尝试以下提示：

• “在我的笔记中搜索‘Docker’”
• “在我的笔记中列出标记文件”
• “我的笔记对系统架构有什么看法？”

______________________________________________________________________

🧪 测试

测试扫描仪

from md_mcp.scanner import MarkdownScanner

scanner = MarkdownScanner("~/notes")
files = scanner.scan()

for f in files:
    print(f"{f.name}: {f.description}")

在本地测试服务器

# Run server directly (stdio mode)
python -m md_mcp.server_runner --folder ~/notes --name test

# Server listens on stdin/stdout for MCP protocol

______________________________________________________________________

📝 Markdown前端支持

md-mcp从YAML frontmatter中提取元数据：

---
title: My Document
description: A brief overview of the document
tags: [project, planning]
---

# Content starts here

提取字段：

• description → 用作资源描述
• 其他字段存储在 frontmatter 字典

如果没有正文，则使用第一段作为描述。

______________________________________________________________________

🚧 路线图

• \[ \] v0.3： 大文件的智能分块
• \[ \] v0.4： 嵌入语义搜索
• \[ \] v1.0： 使用web UI进行所有操作

______________________________________________________________________

🐛 故障排除

“服务器未显示在Claude Desktop中”

1. 检查配置是否已更新：

   md-mcp --status

1. 验证文件是否存在：

   # Windows
   type %APPDATA%\Claude\claude_desktop_config.json

   # Mac/Linux
   cat ~/.config/Claude/claude_desktop_config.json

1. 完全重新启动克劳德桌面

“找不到文件”

# Check what scanner finds
md-mcp --folder ~/notes --scan

“权限被拒绝”

确保文件夹可读：

# Check permissions
ls -la ~/notes

______________________________________________________________________

🏗️ 建筑

┌─────────────────┐
│  Claude Desktop │
│   (MCP Client)  │
└────────┬────────┘
         │ stdio (JSON-RPC)
         │
┌────────▼────────┐
│  md-mcp Server  │
│  (MCP Protocol) │
└────────┬────────┘
         │
┌────────▼────────┐
│ MarkdownScanner │
│  (File Reader)  │
└────────┬────────┘
         │
   ┌─────▼──────┐
   │ Filesystem │
   │  (*.md)    │
   └────────────┘

______________________________________________________________________

🤝 与备选方案的比较

______________________________________________________________________

📚 发展

设置开发环境

git clone https://github.com/ly2xxx/md-mcp.git
cd md-mcp
pip install -e ".[dev]"

运行测试

pytest

格式码

black md_mcp/

______________________________________________________________________

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🙏 学分

灵感来源：

• 模型上下文协议 通过Anthropic
• 网络共享 -杨丽的文件共享工具

______________________________________________________________________

📮 联系

问题：https://github.com/ly2xxx/md-mcp/issues

______________________________________________________________________

建造人： 李阳\ 日期： 2026-02-16

🚀 只需指向一个文件夹即可！