# md-mcp

**Transform from Prompt Engineering to Context Engineering.**

A lightweight Python library that instantly exposes your local markdown documentation, notes, and knowledge bases to **any** AI tool that supports the Model Context Protocol (MCP) – including Claude Desktop.

No embeddings, no preprocessing, and no uploading. Your files stay safely on your local machine, and any real-time updates are instantly reflected in your AI's context.

![md-mcp Web Interface](https://raw.githubusercontent.com/ly2xxx/md-mcp/main/demo/GUI-demo-complete-cut.gif)

![md-mcp Infographic](https://raw.githubusercontent.com/ly2xxx/md-mcp/main/image/md-mcp.png)

---

## 🚀 Quick Start

### 1. Install

#### Option A: Install from pypi

```bash
pip install md-mcp
```

#### Option B: Install from source code

```bash
uv sync
```

### 2. Launch the Web UI (Recommended)

The easiest way to manage your markdown servers is through the visual dashboard:

```bash
md-mcp --web
```

If the command is not recognized (e.g., if the Python scripts directory is not in your system PATH), you can run:

```bash
uv run python -m md_mcp --web
```

*Just point at a folder and go!*

### 3. Or use the CLI

If you prefer the command line:

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

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

---

## 📋 Features

- **Context Engineering**: Feed your AI assistant exactly the right local context to get better answers, eliminating the need to endlessly prompt.
- **Universal MCP Support**: Works natively with Claude Desktop and any other AI tool or agent that supports the Model Context Protocol.
- **Local & Secure First**: Your files never leave your machine. No cloud uploads, no third-party APIs parsing your sensitive notes.
- **Real-time Sync**: Edit your markdown files and the MCP server picks up the changes instantly. No need to regenerate embeddings or re-index.
- **Auto File Watching**: Automatically detects when files are added, modified, or deleted (powered by [watchdog](https://pypi.org/project/watchdog/)). Use the `rescan_folder()` tool in Claude Desktop for manual refresh if needed.
- **Zero Configuration**: Just point at a folder and go.
- **Auto-Discovery**: Recursively finds all `.md` files.
- **Metadata Extraction**: Parses YAML frontmatter and first paragraphs for rich resource descriptions.
- **Search Support**: Built-in search across all files to quickly find the needle in the haystack.
- **Web Interface**: Easy-to-use visual dashboard for non-technical users to manage multiple knowledge bases.
- **Observable by Default**: Optional OpenTelemetry instrumentation (`uv pip install "md-mcp[observability]"`) traces every MCP tool call — an audit trail of what your AI assistant actually did with your notes. See [docker/README.md](docker/README.md#optional-observability-opentelemetry).

---

## 🎯 Use Cases

**1. Personal Knowledge Base**

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

→ Claude can now read your entire Obsidian vault

**2. Project Documentation**

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

→ Claude has full context on your project

**3. Research Papers**

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

→ Claude can reference your research notes

---

## 📖 Advanced Usage commands

### Web Interface (easiest way to use)

```bash
# 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
```

### Add a Markdown Folder

```bash
# 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"
```

### Scan Before Adding (Dry Run)

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

### List Configured Servers

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

### Show Configuration Status

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

### Remove a Server

```bash
md-mcp --remove "My Docs"
```

### Interactive Mode

```bash
md-mcp
# Prompts for folder path
```

---

## 🔧 How It Works

1. **You run the CLI:**

   ```bash
   md-mcp --folder ~/notes --name "Notes"
   ```
2. **md-mcp:**

   - Scans folder for `.md` files
   - Extracts metadata (frontmatter, descriptions)
   - Updates Claude Desktop config
   - Registers MCP server entry
3. **In Claude Desktop:**

   - Restart Claude
   - Server appears in MCP dropdown
   - All markdown files available as resources
   - Use search tools to find content

---

## 📂 What Gets Exposed

Each markdown file becomes an **MCP Resource**:

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

---

## 🛠️ MCP Tools

md-mcp provides three tools to Claude:

### 1. `search_markdown`

Search across all markdown files by content or filename.

**Usage in Claude:**

- **Standard (keyword):** > "Search my notes for 'docker compose'"

⚠️ **Experimental features below: (may not work)**

- **Semantic:** > "Search my docs for 'user authentication' using semantic search" *(Finds related concepts like login, OAuth, etc.)*
- **Hybrid:** > "Search for 'docker setup' using hybrid search" *(Combines exact matching and conceptual matching)*

*(Note: Semantic and hybrid search require `uv pip install "md-mcp[semantic]"`, or installing with the extra flag)*

### 2. `list_files`

List all available markdown files.

**Usage in Claude:**

> "What markdown files do I have about Python?"

### 3. `rescan_folder`

Manually rescan the folder for new, modified, or deleted markdown files. Use this if the automatic file watcher is not available or if files are missing.

**Usage in Claude:**

> "Rescan the markdown folder to find my new notes"

---

## 📋 Requirements

- Python 3.10+
- [mcp](https://pypi.org/project/mcp/) library
- Claude Desktop

---

## 🔧 Configuration

### Claude Desktop Config Location (Automatic)

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

**Linux:** `~/.config/Claude/claude_desktop_config.json`

### Antigravity Config Location (Manual)

**Windows:** `%USERPROFILE%\.gemini\antigravity\mcp_config.json`

Add your config and run **Developer: Reload Window** from the Command Palette (`Ctrl+Shift+P`).

### Config Entry Format

```json
# 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 Code MCP Config (Manual)

For workspace-level tools, use a file at `.vscode/mcp.json`. See [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_other-options-to-add-an-mcp-server).

> [!IMPORTANT]
> For workspace configs, the top-level key is `"servers"`, **not** `"mcpServers"`.

Example `.vscode/mcp.json`:

```json
{
  "servers": {
    "my-notes": {
      "command": "uvx",
      "args": [
        "md-mcp",
        "--folder", "C:\\Users\\Yang\\notes",
        "--name", "my-notes"
      ]
    }
  }
}
```

#### Sample Prompts to Test

Once configured, try these prompts with your AI assistant:

- "Search my-notes for 'Docker'"
- "List markdown files in my-notes"
- "What do my notes say about the system architecture?"
  ![List markdown files](https://raw.githubusercontent.com/ly2xxx/md-mcp/main/image/list-markdown-files.png)

---

## 🧪 Testing

### Test the Scanner

```python
from md_mcp.scanner import MarkdownScanner

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

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

### Test the Server Locally

```bash
# 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 Frontmatter Support

md-mcp extracts metadata from YAML frontmatter:

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

# Content starts here
```

**Extracted fields:**

- `description` → Used as resource description
- Other fields stored in `frontmatter` dict

If no frontmatter, first paragraph is used as description.

---

## 🚧 Roadmap

- [ ] **v0.3:** Smart chunking for large files
- [ ] **v0.4:** Semantic search with embeddings
- [ ] **v1.0:** Use web UI for all operations

---

## 🐛 Troubleshooting

### "Server not showing in Claude Desktop"

1. Check config was updated:

   ```bash
   md-mcp --status
   ```
2. Verify file exists:

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

   # Mac/Linux
   cat ~/.config/Claude/claude_desktop_config.json
   ```
3. Restart Claude Desktop completely

### "No files found"

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

### "Permission denied"

Make sure the folder is readable:

```bash
# Check permissions
ls -la ~/notes
```

---

## 🏗️ Architecture

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

---

## 🤝 Comparison to Alternatives

| Feature      | md-mcp     | Manual MCP Server | File Upload |
| ------------ | ---------- | ----------------- | ----------- |
| Setup Time   | 30 seconds | Hours             | Per-session |
| Auto-Updates | ✅         | ❌                | ❌          |
| Full Folder  | ✅         | ✅                | ❌          |
| Search       | ✅         | Custom            | ❌          |
| One Command  | ✅         | ❌                | ❌          |

---

## 📚 Development

### Setup Dev Environment

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

### Run Tests

Run standard unit tests:

```bash
uv run pytest
```

Run AI Agent integration tests (BDD + DeepEval):

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

*This project champions a new AI testing standard by combining Behavior-Driven Development (pytest-bdd) with LLM-as-a-judge metrics (DeepEval) to rigorously evaluate Agentic RAG workflows.*

![1784038811777](image/README/BDD-deepeval.png)

### Format Code

```bash
uv run black md_mcp/
```

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Credits

Inspired by:

- [Model Context Protocol](https://github.com/modelcontextprotocol) by Anthropic
- [netshare](https://github.com/ly2xxx/netshare) - File sharing tool by Yang Li

---

## 📮 Contact

Issues: https://github.com/ly2xxx/md-mcp/issues

---

**Built by:** Yang Li
**Date:** 2026-02-16

🚀 **Just point at a folder and go!**
![point and go](https://raw.githubusercontent.com/ly2xxx/md-mcp/main/demo/point-and-go.png)