Name: Markdown上下文服务库
Author: ly2xxx

使用说明

md-mcp

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

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

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

🚀 快速开始

1.安装

选项A：从pypi安装

pip install md-mcp

选项B：从源代码安装

uv sync

2.启动Web UI（推荐）

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

md-mcp --web

如果无法识别该命令（例如，如果Python脚本目录不在您的系统PATH中），您可以运行：

uv run python -m 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和第一段，以获取丰富的资源描述。
搜索支持：在所有文件中内置搜索功能，可以快速找到大海捞针。
网络界面：易于使用的可视化仪表板，供非技术用户管理多个知识库。
默认情况下可观察：可选的OpenTetry仪器(uv pip install "md-mcp[observability]")跟踪每个MCP工具调用——这是对你的AI助手对你的笔记实际做了什么的审计跟踪。看 docker/README.md.

🎯 用例

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界面（最简单的使用方法）

# Direct command (if in PATH)
md-mcp --web

# Or via Python module
uv run python -m md_mcp --web

# You can optionally specify a custom port (default is 5000)
md-mcp --web --port 8080
# or: uv run python -m 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

🔧 运作原理

您运行CLI：
```
md-mcp --folder ~/notes --name "Notes"
```
md-mcp：
- 扫描文件夹以查找 .md 文件
- 提取元数据（封面、描述）
- 更新Claude桌面配置
- 注册MCP服务器条目
在克劳德桌面中：
- 重新启动克劳德
- 服务器出现在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'” （结合精确匹配和概念匹配）

（注：语义和混合搜索需要 uv pip install "md-mcp[semantic]"，或安装额外的标志）

2. `list_files`

列出所有可用的markdown文件。

Claude中的用法：

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

3. `rescan_folder`

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

Claude中的用法：

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

📋 需求

Python 3.10+
主控程序图书馆
Claude 桌面版

🔧 配置

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).

配置条目格式

# With uv installed
{
  "mcpServers": {
    "my-notes": {
      "command": "uvx",
      "args": [
        "md-mcp",
        "--folder", "C:\\Users\\Yang\\notes",
        "--name", "my-notes"
      ]
    }
  }
}

# Without uv installed
{
  "mcpServers": {
    "my-notes": {
      "command": "python",
      "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": "uvx",
      "args": [
        "md-mcp",
        "--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)
uv run 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中”

检查配置是否已更新：
```
md-mcp --status
```

验证文件是否存在：

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

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

完全重新启动克劳德桌面

“找不到文件”

# 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)    │
   └────────────┘

🤝 与备选方案的比较

功能	md-mcp	手动mcp服务器	文件上传
设置时间	30秒	小时	每次会话
自动更新	✅	❌	❌
完整文件夹	✅	✅	❌
搜索	✅	自定义	❌
一个命令	✅	❌	❌

📚 发展

设置开发环境

git clone https://github.com/ly2xxx/md-mcp.git
cd md-mcp
uv sync --extra dev
#Equivalent to (pip install -e ".[dev]")

运行测试

运行标准单元测试：

uv run pytest

运行AI Agent集成测试（BDD+DeepEval）：

uv run deepeval test run sample-client/tests/step_defs/test_search_markdown.py

该项目通过将行为驱动开发（pytest-bdd）与LLM作为判断指标（DeepEval）相结合，严格评估代理RAG工作流程，从而支持一种新的AI测试标准。

格式码

uv run black md_mcp/

📄 许可证

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

🙏 鸣谢

灵感来源：

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

📮 联系

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

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

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

使用说明

md-mcp

🚀 快速开始

1.安装

选项A：从pypi安装

选项B：从源代码安装

2.启动Web UI（推荐）

3.或使用CLI

📋 特性

🎯 用例

📖 高级用法命令

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

添加Markdown文件夹

添加前扫描（干运行）

列出已配置的服务器

显示配置状态

删除服务器

交互模式

🔧 运作原理

📂 暴露了什么

🛠️ MCP工具

1. search_markdown

2. list_files

3. rescan_folder

📋 需求

🔧 配置

Claude桌面配置位置（自动）

反重力配置位置（手动）

配置条目格式

VS代码MCP配置（手动）

样品测试提示

🧪 测试

测试扫描仪

在本地测试服务器

📝 Markdown前端支持

🚧 路线图

🐛 故障排除

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

“找不到文件”

“权限被拒绝”

🏗️ 建筑学

🤝 与备选方案的比较

📚 发展

设置开发环境

运行测试

格式码

📄 许可证

🙏 鸣谢

📮 联系

相关 MCP

AI上下文增强服务器

网页内容抓取服务器

知识图谱记忆服务器

顺序思维服务器

Figma MCP服务器

GitHub API服务器

1. `search_markdown`

2. `list_files`

3. `rescan_folder`