内容
# md-mcp
**从提示工程转变为上下文工程。**
一个轻量级的Python库，立即将您的本地Markdown文档、笔记和知识库暴露给**任何**支持模型上下文协议（MCP）的AI工具，包括Claude Desktop。
无需嵌入，无需预处理，也无需上传。您的文件安全地保留在本地机器上，任何实时更新都立即反映在AI的上下文中。
---
## 🚀 快速开始
### 1. 安装
#### 选项 A: 从 pypi 安装
```bash
pip install md-mcp
```
#### 选项 B: 从源代码安装
```bash
pip install -e .
```
### 2. 启动 Web UI（推荐）
管理 Markdown 服务器的最简单方法是使用可视化仪表盘：
```bash
md-mcp --web
```
如果命令无法识别（例如，Python 脚本目录不在系统 PATH 中），您可以运行：
```bash
python -m md_mcp --web
```
*只需指向一个文件夹，然后开始！*
### 3. 或使用 CLI
如果您更喜欢命令行：
```bash
# 暴露一个 Markdown 文件夹
md-mcp --folder ~/Documents/notes --name "我的笔记"
# 就是这样！重启 Claude Desktop，它就可用了。
```
---
## 📋 功能
- **上下文工程**：为 AI 助手提供恰到好处的本地上下文，以获得更好的答案，消除无休止提示的需要。
- **通用 MCP 支持**：与 Claude Desktop 和任何其他支持模型上下文协议的 AI 工具或代理原生兼容。
- **本地和安全第一**：您的文件永远不会离开您的机器。无需云上传，无需第三方 API 解析您的敏感笔记。
- **实时同步**：编辑您的 Markdown 文件，MCP 服务器会立即捕获更改。无需重新生成嵌入或重新索引。
- **自动文件监视**：自动检测文件何时被添加、修改或删除（由 [watchdog](https://pypi.org/project/watchdog/) 提供支持）。在需要时，在 Claude Desktop 中使用 `rescan_folder()` 工具进行手动刷新。
- **零配置**：只需指向一个文件夹，然后开始。
- **自动发现**：递归查找所有 `.md` 文件。
- **元数据提取**：解析 YAML 前置信息和第一段以获取丰富的资源描述。
- **搜索支持**：内置搜索功能，跨所有文件快速找到所需内容。
- **Web 界面**：易于使用的可视化仪表盘，供非技术用户管理多个知识库。
---
## 🎯 用例
**1. 个人知识库**
```bash
md-mcp --folder ~/obsidian-vault --name "Obsidian"
```
→ Claude 现在可以读取您的整个 Obsidian 保险库
**2. 项目文档**
```bash
md-mcp --folder ~/code/myproject/docs --name "项目文档"
```
→ Claude 拥有项目的完整上下文
**3. 研究论文**
```bash
md-mcp --folder ~/research/papers-md --name "研究"
```
→ Claude 可以引用您的研究笔记
---
## 📖 高级用法命令
### Web 界面（最简单的使用方式）
```bash
# 直接命令（如果在 PATH 中）
md-mcp --web
# 或通过 Python 模块
python -m md_mcp --web
# 您可以可选地指定自定义端口（默认为 5000）
md-mcp --web --port 8080
# 或：python -m md_mcp --web --port 8080
```
### 添加 Markdown 文件夹
```bash
# 显式命名
md-mcp --folder /path/to/docs --name "我的文档"
# 自动从文件夹命名
md-mcp --folder ~/notes
# 创建名为“notes”的服务器
# 别名：--add
md-mcp --add ~/work-docs --name "工作"
```
### 扫描前添加（干运行）
```bash
md-mcp --folder ~/notes --scan
# 显示将要暴露的文件
```
### 列出已配置的服务器
```bash
md-mcp --list
# 显示所有 md-mcp 服务器
```
### 显示配置状态
```bash
md-mcp --status
# 显示 Claude 配置路径和所有服务器
```
### 删除服务器
```bash
md-mcp --remove "我的文档"
```
### 交互模式
```bash
md-mcp
# 提示文件夹路径
```
---
## 🔧 工作原理
1. **您运行 CLI：**
```bash
md-mcp --folder ~/notes --name "笔记"
```
2. **md-mcp：**
- 扫描文件夹中的 `.md` 文件
- 提取元数据（前置信息，描述）
- 更新 Claude Desktop 配置
- 注册 MCP 服务器条目
3. **在 Claude Desktop 中：**
- 重启 Claude
- 服务器出现在 MCP 下拉菜单中
- 所有 Markdown 文件作为资源可用
- 使用搜索工具查找内容
---
## 📂 暴露的内容
每个 Markdown 文件都成为一个 **MCP 资源**：
```json
{
"uri": "md://notes/project-plan.md",
"name": "项目计划",
"description": "从前置信息或第一段自动提取",
"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+
- [mcp](https://pypi.org/project/mcp/) 库
- Claude Desktop
---
## 🔧 配置
### Claude Desktop 配置位置（自动）
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
### Antigravity 配置位置（手动）
**Windows:** `%USERPROFILE%\.gemini\antigravity\mcp_config.json`
添加您的配置并运行 **Developer: Reload Window** 从命令调色板（`Ctrl+Shift+P`）。
### 配置条目格式
```json
{
"mcpServers": {
"my-notes": {
"command": "C:\\Python\\python.exe",
"args": [
"-m", "md_mcp.server_runner",
"--folder", "C:\\Users\\Yang\\notes",
"--name", "my-notes"
]
}
}
}
```
### VS Code MCP 配置（手动）
对于工作区级工具，请在 `.vscode/mcp.json` 处使用文件。参见 [官方 VS Code MCP 文档](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_other-options-to-add-an-mcp-server).
> [!IMPORTANT]
> 对于工作区配置，顶级键是 `"servers"`，**不是** `"mcpServers"`。
示例 `.vscode/mcp.json`：
```json
{
"servers": {
"my-notes": {
"command": "C:\\Python\\python.exe",
"args": [
"-m", "md_mcp.server_runner",
"--folder", "C:\\Users\\Yang\\notes",
"--name", "my-notes"
]
}
}
}
```
#### 测试示例提示
配置完成后，请与 AI 助手尝试这些提示：
- "在 my-notes 中搜索 'Docker'"
- "列出 my-notes 中的 Markdown 文件"
- "我的笔记中关于系统架构的内容是什么？"
---
## 🧪 测试
### 测试扫描器
```python
from md_mcp.scanner import MarkdownScanner
scanner = MarkdownScanner("~/notes")
files = scanner.scan()
for f in files:
print(f"{f.name}: {f.description}")
```
### 在本地测试服务器
```bash
# 直接运行服务器（stdio 模式）
python -m md_mcp.server_runner --folder ~/notes --name test
# 服务器通过 stdin/stdout 监听 MCP 协议
```
---
## 📝 Markdown 前置信息支持
md-mcp 从 YAML 前置信息中提取元数据：
```markdown
---
title: 我的文档
description: 文档的简要概述
tags: [项目, 规划]
---
# 内容从这里开始
```
**提取的字段：**
- `description` → 用作资源描述
- 其他字段存储在 `frontmatter` 字典中
如果没有前置信息，则使用第一段作为描述。
---
## 🚧 路线图
- [ ] **v0.3:** 大型文件的智能分块
- [ ] **v0.4:** 具有嵌入的语义搜索
- [ ] **v1.0:** 使用 Web UI 进行所有操作
---
## 🐛 故障排除
### "服务器未在 Claude Desktop 中显示"
1. 检查配置是否已更新：
```bash
md-mcp --status
```
2. 验证文件是否存在：
```bash
# Windows
type %APPDATA%\Claude\claude_desktop_config.json
# Mac/Linux
cat ~/.config/Claude/claude_desktop_config.json
```
3. 完全重启 Claude Desktop
### "未找到文件"
```bash
# 检查扫描器找到的内容
md-mcp --folder ~/notes --scan
```
### "权限被拒绝"
确保文件夹可读：
```bash
# 检查权限
ls -la ~/notes
```
---
## 🏗️ 架构
```
┌─────────────────┐
│ Claude Desktop │
│ （MCP 客户端） │
└────────┬────────┘
│ stdio（JSON-RPC）
│
┌────────▼────────┐
│ md-mcp 服务器 │
│ （MCP 协议） │
└────────┬────────┘
│
┌────────▼────────┐
│ Markdown 扫描器 │
│ （文件读取器） │
└────────┬────────┘
│
┌─────▼──────┐
│ 文件系统 │
│ （*.md） │
└────────────┘
```
---
## 🤝 与替代品比较
| 功能 | md-mcp | 手动 MCP 服务器 | 文件上传 |
|---------|--------|-------------------|-------------|
| 设置时间 | 30 秒 | 小时 | 每次会话 |
| 自动更新 | ✅ | ❌ | ❌ |
| 完整文件夹 | ✅ | ✅ | ❌ |
| 搜索 | ✅ | 自定义 | ❌ |
| 一条命令 | ✅ | ❌ | ❌ |
---
## 📚 开发
### 设置开发环境
```bash
git clone https://github.com/ly2xxx/md-mcp.git
cd md-mcp
pip install -e ".[dev]"
```
### 运行测试
```bash
pytest
```
### 格式化代码
```bash
black md_mcp/
```
---
## 📄 许可证
该项目使用 MIT 许可证 - 参见 [LICENSE](LICENSE) 文件以获取详细信息。
---
## 🙏 致谢
灵感来自：
- [模型上下文协议](https://github.com/modelcontextprotocol) 由 Anthropic 提出
- [netshare](https://github.com/ly2xxx/netshare) - Yang Li 的文件共享工具
---
## 📮 联系方式
问题：https://github.com/ly2xxx/md-mcp/issues
---
**构建者：** Yang Li
**日期：** 2026-02-16
🚀 **只需指向一个文件夹，然后开始！**
