file-vault-mcp

A local-first Model Context Protocol (MCP) server that gives Claude a persistent, file-based knowledge base. Store notes, search across them, and crawl entire documentation sites into searchable markdown — all stored locally on your machine.

Features

• Note CRUD — create, read, update, delete markdown notes with YAML frontmatter
• Full-text search — ranked search across titles, tags, paths, and content body
• Documentation ingestion — BFS-crawl any doc site and store every page as a searchable note
• Organized namespaces — global/, repos/, docs/ for cross-project notes, per-repo notes, and ingested docs
• Puppeteer fallback — automatically launches a headless browser for JS-heavy pages when static extraction returns too little content
• Configurable — pass your knowledge base path and settings via CLI args or environment variables

Quick Start

With Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "knowledge-base": {
      "command": "npx",
      "args": [
        "-y",
        "file-vault-mcp",
        "--kb-path", "/Users/YOUR_NAME/my-knowledge-base"
      ]
    }
  }
}

With Claude Code

claude mcp add knowledge-base -- npx -y file-vault-mcp --kb-path /Users/YOUR_NAME/my-knowledge-base

Global Install

npm install -g file-vault-mcp
file-vault-mcp --kb-path ~/my-knowledge-base

Configuration

Configuration can be passed as CLI arguments or environment variables. CLI args take precedence.

| CLI Flag | Env Variable | Default | Description | |---|---|---|---| | --kb-path | KNOWLEDGE_BASE_PATH | ./knowledge-base (relative to package root) | Absolute or relative path to the knowledge base directory | | --min-content-length | MIN_CONTENT_LENGTH | 200 | Minimum markdown character count before Puppeteer fallback triggers during ingestion |

Using environment variables

{
  "mcpServers": {
    "knowledge-base": {
      "command": "npx",
      "args": ["-y", "file-vault-mcp"],
      "env": {
        "KNOWLEDGE_BASE_PATH": "/Users/YOUR_NAME/my-knowledge-base",
        "MIN_CONTENT_LENGTH": "200"
      }
    }
  }
}

Tools

create_note

Create or update a note. If the note already exists, it is updated and the original creation date is preserved.

| Parameter | Type | Required | Description | |---|---|---|---| | path | string | yes | Relative path without .md extension (e.g. global/my-note, repos/myrepo/setup) | | title | string | yes | Human-readable title | | content | string | yes | Markdown content | | tags | string[] | no | Tags for categorization (max 20) |

get_note

Retrieve the full content of a note including YAML frontmatter.

| Parameter | Type | Required | Description | |---|---|---|---| | path | string | yes | Relative path to the note |

list_notes

List all notes with titles, tags, and last-updated timestamps. Use prefix to scope the listing.

| Parameter | Type | Required | Description | |---|---|---|---| | prefix | string | no | Path prefix filter (e.g. global, repos/myrepo, docs/stripe-api) |

search_notes

Full-text search across all notes. Returns results ranked by relevance with excerpt context.

Scoring: title match (+10), tag match (+5), path match (+3), content occurrence (+1 each, capped at 20).

| Parameter | Type | Required | Description | |---|---|---|---| | query | string | yes | Search query (multi-word supported) | | prefix | string | no | Limit search to a path prefix | | limit | number | no | Max results to return (default 20, max 100) |

delete_note

Permanently delete a note.

| Parameter | Type | Required | Description | |---|---|---|---| | path | string | yes | Relative path to the note | | confirm | boolean | yes | Must be true to proceed |

ingest_docs_from_url

Crawl a documentation website and store all pages as searchable markdown notes under docs/<name>/.

| Parameter | Type | Required | Description | |---|---|---|---| | url | string | yes | Starting URL to crawl | | name | string | yes | Identifier for the doc set (e.g. stripe-api, react-docs) | | max_depth | number | no | Link depth to follow (default 2, max 10). 0 = start page only | | max_pages | number | no | Hard cap on pages to crawl (default 100, max 500) | | overwrite | boolean | no | If true, re-crawl and overwrite existing pages. Default false (incremental) |

How it works:

1. BFS-crawls from the start URL, following same-domain links up to max_depth
2. Extracts content using Cheerio (static HTML) with automatic Puppeteer fallback for JS-heavy sites
3. Converts HTML to clean markdown via Turndown
4. Stores each page with YAML frontmatter (title, tags, source URL, timestamps)
5. Skips binary files, auth pages, and already-stored pages (unless overwrite=true)

Knowledge Base Structure

knowledge-base/
  global/           # Cross-project notes
    coding-patterns.md
    architecture-decisions.md
  repos/            # Per-repository notes
    my-api/
      setup.md
      deployment.md
  docs/             # Ingested documentation sites
    stripe-api/
      index.md
      api/charges.md
      api/tokens.md
    react-docs/
      hooks/use-state.md

Each note is a markdown file with YAML frontmatter:

---
title: My Note Title
tags:
  - architecture
  - backend
created: '2025-01-15T10:30:00.000Z'
updated: '2025-01-15T14:22:00.000Z'
type: note
---

Your markdown content here...

Ingested docs include additional metadata:

---
title: Authentication
tags:
  - docs
  - stripe-api
created: '2025-01-15T10:30:00.000Z'
updated: '2025-01-15T10:30:00.000Z'
type: documentation
source: 'https://docs.stripe.com/api/authentication'
---

Development

git clone <repo-url>
cd knowledge-base-mcp
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Type check (separate from build)
npm run typecheck

Requirements

• Node.js >= 18

License

MIT