MarkScribe

Convention-aware markdown MCP server for the Model Context Protocol. MarkScribe lets AI agents read, write, search, and validate markdown files — enforcing conventions through user-defined YAML schemas. Works with any markdown directory: Obsidian vaults, Foam workspaces, digital gardens, documentation repos.

Features

• Read, write, move, and delete notes with atomic file operations

• Full-text search (BM25 ranking) across content and frontmatter

• Wikilink-aware: backlinks, broken link detection, orphan finding, unlinked mention discovery

• YAML frontmatter parsing, validation, and bulk updates

• Tag management (frontmatter and inline)

• Convention enforcement via schemas — note schemas validate frontmatter/content, folder schemas enforce structural rules

• Convention cascade: _conventions.md files scope schemas to directory subtrees

• Path security: .obsidian/, .git/, node_modules/ always blocked

Installation

npm install -g markscribe

Usage

As an MCP server

{
  "mcpServers": {
    "markscribe": {
      "command": "markscribe",
      "args": ["--root", "/path/to/your/notes"]
    }
  }
}

CLI flags

Per-directory config

Place a .markscribe/config.yaml in your root directory:

paths:
  blocked:
    - private/
    - drafts/
  allowed_extensions:
    - .md
    - .markdown
    - .txt
search:
  max_results: 50
  excerpt_chars: 40

Schemas

Schemas define conventions for your notes and folders. Place them in your schemas directory (~/.markscribe/schemas/ by default).

Note schema — validates frontmatter fields and content rules:

name: blog-post
description: Blog post with required metadata
type: note
frontmatter:
  fields:
    title:
      type: string
      required: true
    tags:
      type: list
      required: true
content:
  rules:
    - name: has-outgoing-link
      check: hasPattern
      pattern: "\\[\\[.+?\\]\\]"

Folder schema — enforces structural rules on directories:

name: project-folder
description: Project folder with hub note
type: folder
noteSchemas:
  default: blog-post
  hub: project-hub
classification:
  supplemental: [assets, templates]
  skip: [archive]
hub:
  detection:
    - pattern: "_{{folderName}}"
  required: true

Notes opt into schemas via note_schema: <name> in frontmatter, or automatically via the convention cascade (_conventions.md files).

Tools

Compatible viewers

MarkScribe works with any tool that reads markdown files:

• Obsidian — PKM app with graph view and community plugins

• Foam — VS Code extension for linked notes

• Logseq — Outliner with bidirectional links

• Any text editor or static site generator

Acknowledgements

Built with Claude Code.

License

MIT