Automation & MCP

The desktop app can run a small HTTP API on your own machine so that scripts, automation tools, and AI assistants can work with your Markdown notes — including the ones on a NAS. It is off by default.

There is also a companion Model Context Protocol server, md-reader-mcp, that plugs this API into MCP clients such as Claude Desktop and Claude Code.

The API is a desktop feature. The browser version can’t run a local server.

Turning it on

Preferences ▸ Local API ▸ On.

The panel then shows:

a URL — http://127.0.0.1:41100 by default
a bearer token — every request must send Authorization: Bearer <token>

You can Copy either, Show the token, or generate a New one (which invalidates the old token immediately).

The API binds to 127.0.0.1 only — it is not reachable from your network or the internet. Any program on your computer that has the token can read and write your notes and add or remove server connections, so treat the token like a password. See the Privacy Policy for the full description.

What it can do

Method & path	Purpose
`GET /v1/health`	version and connection count
`GET /v1/capabilities`	machine-readable permissions: what is reachable (remote connections only, never the local disk), and each operation’s `read` / `write` / `admin` access
`GET /v1/connections`	list configured servers (no passwords)
`POST /v1/connections`	add a server (SFTP / FTP / FTPS / WebDAV / SMB)
`DELETE /v1/connections/{id}`	remove a server and its stored password
`POST /v1/connections/{id}/test`	check a server is reachable
`GET /v1/notes?connection={id}&path=/`	list the Markdown tree under a folder
`GET /v1/note?connection={id}&path=/x.md`	read a note — content, front matter, tags
`GET /v1/note?…&render=1`	…also return rendered HTML
`PUT /v1/note?connection={id}&path=/x.md`	create or overwrite a note
`GET /v1/search?connection={id}&q=…`	full-text search
`GET /v1/backlinks?connection={id}&path=/x.md`	notes that link to this one
`GET /v1/tags?connection={id}`	every `#tag` / front-matter tag with counts
`POST /v1/render`	render arbitrary Markdown to HTML

Requests and responses are JSON. PUT /v1/note also accepts a raw Markdown body.

By default the API only reaches your saved server connections. To let an assistant use a local folder (a vault), open it, go to the Files tab and tick Share this folder with the Local API / AI. Then:

it is read-only unless you also tick Allow editing;
clients address notes as a vault id + relative path — your real file-system paths are never sent;
only Markdown files inside the folder are reachable; .., absolute paths, symlinks that lead outside the folder, and hidden folders are refused;
un-ticking the box removes access immediately.

Method & path	Purpose
`GET /v1/vaults`	the folders you have shared, with `read` / `write` access
`GET /v1/vault/notes?vault={id}`	list notes
`GET /v1/vault/note?vault={id}&path=sub/x.md`	read a note (`&render=1` for HTML)
`PUT /v1/vault/note?vault={id}&path=sub/x.md`	write — `403` unless editing is allowed
`GET /v1/vault/search?vault={id}&q=…`	full-text search
`GET /v1/vault/backlinks?vault={id}&path=x.md`	notes linking to this one
`GET /v1/vault/tags?vault={id}`	tags with counts

An unknown or un-shared vault id returns 404, the same either way. GET /v1/capabilities describes all of this in machine-readable form, including which vaults are currently shared and with what access, so clients can check the boundary before calling a tool.

Example

TOKEN=…                     # from Preferences ▸ Local API
BASE=http://127.0.0.1:41100

# list your servers
curl -s -H "Authorization: Bearer $TOKEN" $BASE/v1/connections

# read a note as HTML
curl -s -H "Authorization: Bearer $TOKEN" \
  "$BASE/v1/note?connection=<id>&path=/notes/todo.md&render=1"

# write one
curl -s -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: text/markdown" \
  --data-binary '# Done

- shipped the thing' \
  "$BASE/v1/note?connection=<id>&path=/notes/log.md"

Using it from an AI client (MCP)

md-reader-mcp exposes the API as MCP tools: list_connections, add_connection, list_notes, read_note, write_note, search_notes, backlinks, list_tags, render_markdown, and more.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "md-reader": {
      "command": "npx",
      "args": ["-y", "md-reader-mcp"],
      "env": {
        "MDR_API_URL": "http://127.0.0.1:41100",
        "MDR_API_TOKEN": "paste-the-token-from-preferences"
      }
    }
  }
}

Claude Code:

claude mcp add md-reader -e MDR_API_TOKEN=… -- npx -y md-reader-mcp

Keep Markdown Reader running with the Local API on while you use the tools.

Other tools