# md-reader-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that gives an
AI client (Claude Desktop, Claude Code, …) structured access to your **Markdown
notes on a NAS** — read, search, write, tags, backlinks, and rendering — through
the local API of the [**Markdown Reader & Editor**](https://markdown-reader-editor.netlify.app)
desktop app.

The app is the hub: connections (SMB / SFTP / FTP / WebDAV, e.g. a ZimaOS box)
are configured there, passwords live in your OS keychain, and this server is a
thin bridge over the app's `127.0.0.1` API.

## Setup

1. **Markdown Reader ▸ Preferences ▸ Local API** — turn it **On**. It shows a URL
   (`http://127.0.0.1:41100` by default) and a bearer token.
2. Add this server to your MCP client. For **Claude Desktop**
   (`claude_desktop_config.json`):

   ```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"
         }
       }
     }
   }
   ```

   For **Claude Code**: `claude mcp add md-reader -e MDR_API_TOKEN=… -- npx -y md-reader-mcp`

3. Keep Markdown Reader running while you use the tools.

## Tools

| Tool | What it does |
| ---- | ------------ |
| `list_connections` | the servers configured in the app |
| `add_connection` | add a NAS / server (name, protocol, host, credentials…) |
| `remove_connection` / `test_connection` | manage a connection |
| `list_notes` | the Markdown tree under a folder |
| `read_note` | content + front matter + tags (+ `render: true` for HTML) |
| `write_note` | create or overwrite a note |
| `search_notes` | full-text search |
| `backlinks` | notes that link to a given note |
| `list_tags` | every `#tag` / front-matter tag with counts |
| `render_markdown` | render arbitrary Markdown with the app's engine |

## Notes

- The API is `127.0.0.1`-only and token-gated. This server never sees your
  passwords — only the token, which you can regenerate in Preferences.
- `write_note` overwrites. Run your MCP client so it confirms tool calls if you
  want a checkpoint before writes.

## License

MIT © Vasyl Madei