MCP 服务器

markdown-publish

Enables AI to search, retrieve, list notes, and get backlinks from a published Markdown vault (Obsidian) via GitHub Pages.

README

markdown-publish — Claude Code plugin

Publish your Obsidian / Markdown vault as a website in one chat — then read it back through AI.

</div>

This plugin bundles two things that work together:

	What it does
🚀 `/publish-vault` skill	Tell Claude "publish my vault" and it ships your notes to GitHub Pages — in your own account, for free.
🔌 MCP server	Point any MCP client (Claude Desktop, Cursor, Claude Code) at your published site so the AI can `search_notes`, `get_note`, `list_notes`, and `get_backlinks`.

Both are powered by the markdown-publish static-site engine: an Obsidian vault → a fast, searchable site with backlinks, a knowledge graph, and canvas boards.

Install

From Claude Code:

/plugin marketplace add abstractwebunit/markdown-publish-plugin
/plugin install markdown-publish

That gives you the /publish-vault skill and the markdown-publish MCP server.

1. Publish a vault — the `publish-vault` skill

You: publish my Obsidian vault at ~/Notes

Claude walks you through it and always shows a plain-language summary before anything is created:

Готов опубликовать твой vault. Вот что получится:

  📁 Заметки из:   /home/me/Notes
  🌐 Адрес сайта:  https://me.github.io/notes/
  📦 Репозиторий:  github.com/me/notes  (публичный, создам новый)
  🏷  Название:     Notes
  🌍 Язык:         ru

Публикуем? (да / изменить / отмена)

Say да and it:

validates the build locally (catches a broken vault early),
creates a new public GitHub repo in your account,
commits your vault + a GitHub Actions workflow,
enables GitHub Pages and waits for the build,
hands you the live URL.

Everything runs under your GitHub login — no backend, no cost, you own it.

Requirements: the gh CLI installed and authenticated (gh auth login).

2. Read your notes from AI — the MCP server

Once your vault is live (or even a local build), connect it to an AI client by setting one environment variable to your site:

MARKDOWN_PUBLISH_SOURCE = https://me.github.io/notes/

It also accepts a local directory (a built site / bundle root) so you can query notes before publishing:

MARKDOWN_PUBLISH_SOURCE = /path/to/built-site

Now the AI has four tools over your vault:

Tool	Description
`search_notes(query, limit?)`	Keyword search → title, slug, url, snippet
`get_note(slug)`	Full markdown of one note + its backlinks
`list_notes()`	Every note (title, slug, url)
`get_backlinks(slug)`	What links to this note

You: what did I write about dopamine in my notes?

Claude: (calls search_notes("dopamine") → get_note(...)) In your note "Habits & Reward" you wrote… [links to your real notes]

Manual MCP config (without the plugin)

The server is a single zero-dependency Node file. Any MCP client config:

{
  "mcpServers": {
    "markdown-publish": {
      "command": "node",
      "args": ["/path/to/markdown-publish-plugin/mcp/server.mjs"],
      "env": { "MARKDOWN_PUBLISH_SOURCE": "https://me.github.io/notes/" }
    }
  }
}

You can also pass the source as a flag: node mcp/server.mjs --source <url|dir>.

How it fits together

   ~/Notes  ──/publish-vault──▶  github.com/you/notes  ──Actions──▶  GitHub Pages
   (vault)        (skill)            (your repo)         (engine)      (live site)
                                                                          │
                                                            content/*.json bundle
                                                                          │
                                          MARKDOWN_PUBLISH_SOURCE ──▶  MCP server
                                                                          │
                                              Claude Desktop / Cursor / Claude Code

The published site emits a machine-readable content/ bundle (search-index.json, notes/<slug>.json, graph.json). The MCP server reads exactly those files — over HTTP for a published site, or from disk for a local build.