# SoloMD

> SoloMD is an open-source MCP server for knowledge and memory. Local MCP server that reads and searches a folder of Markdown notes for AI assistants. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** macOS, Windows, Linux, CLI, self-hosted
- **Website:** https://solomd.app
- **Repository:** https://github.com/zhitongblog/solomd/tree/HEAD/mcp-server
- **MCP Registry name:** io.github.zhitongblog/solomd
- **Categories:** knowledge and memory, productivity
- **Listing updated:** 2026-11-16

## About

This is a standalone Rust binary that points at one or more SoloMD vaults, which are ordinary folders of Markdown files. Each vault gets an alias, and the first becomes the default for tool calls. Per-vault AutoGit histories stay independent.

The 16 tools cover listing notes, reading one with its front matter, headings, tags and wikilinks, substring or regex search capped at 200 hits, backlinks, tag counts, outlines and task checkboxes. History tools show an AutoGit commit log and diffs, and others report sync status, build share URLs and read agent traces.

It is read-only by default. Writing, appending, rolling back a note and exporting require starting with --allow-write; until then those tools fail with a restart message. The editor itself is a free MIT-licensed Markdown app for macOS, Windows, Linux, iOS and Android.

## Features

- **Note listing and reading:** Lists notes with metadata and reads one with front matter, headings, tags and wikilinks.
- **Search:** Runs substring or regex search, capped at 200 hits with context.
- **Backlinks and tags:** Finds notes linking to a note and counts tags across the vault.
- **Tasks and outlines:** Lists checkbox tasks and heading outlines.
- **AutoGit history:** Shows commit logs and diffs for a note.
- **Multiple vaults:** Registers several workspaces with aliases.
- **Opt-in writing:** Write, append, rollback and export tools need --allow-write.

## Good for

- Ask an assistant to find every open task in a notes vault
- Trace which notes link to a given note
- Review how a note changed over time
- Have an agent append meeting notes to a Markdown folder when allowed

## Install

### Claude Code (Terminal)

```sh
claude mcp add solomd -- npx -y https://github.com/zhitongblog/solomd/releases/download/v4.14.11/solomd-mcp-4.14.11.mcpb
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "solomd": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/zhitongblog/solomd/releases/download/v4.14.11/solomd-mcp-4.14.11.mcpb"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "solomd": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/zhitongblog/solomd/releases/download/v4.14.11/solomd-mcp-4.14.11.mcpb"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "solomd": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/zhitongblog/solomd/releases/download/v4.14.11/solomd-mcp-4.14.11.mcpb"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "solomd": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/zhitongblog/solomd/releases/download/v4.14.11/solomd-mcp-4.14.11.mcpb"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "solomd": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/zhitongblog/solomd/releases/download/v4.14.11/solomd-mcp-4.14.11.mcpb"
      ]
    }
  }
}
```

## Tools

- `list_notes`: Walks the vault and returns note metadata.
- `read_note`: Full content of one note with front matter, headings, tags and wikilinks.
- `search`: Substring or regex search across the vault.
- `get_backlinks`: Notes that wikilink a given note.
- `list_tags`: Aggregated tag counts.
- `get_outline`: Heading outline of one note.
- `list_tasks`: Checkbox tasks across the vault.
- `autogit_log`: Commit history of one note.
- `autogit_diff`: Diff of a note between two commits.
- `sync_status`: GitHub sync state.
- `share_url`: Public share URL for a note.
- `read_agent_trace`: Steps of one agent run.
- `write_note`: Creates a note; needs --allow-write.
- `append_to_note`: Appends text to a note; needs --allow-write.
- `autogit_rollback`: Restores a note from a commit; needs --allow-write.
- `export_note`: Exports a note to html, md, txt or docx; needs --allow-write.

## FAQ

### Is it read-only?

By default yes; write_note, append_to_note, autogit_rollback and export_note need --allow-write.

### How many tools are there?

16 tools.

### Which clients can use it?

Claude Code, Codex CLI, Cursor, Continue and any MCP client.

### How does it run?

The client starts the solomd-mcp binary over stdio with one or more --workspace paths.

### Is SoloMD free?

Yes. SoloMD is open source, so you can use and self-host it for free.

### How do I add SoloMD to Claude Code?

Run this command in your terminal: claude mcp add solomd -- npx -y https://github.com/zhitongblog/solomd/releases/download/v4.14.11/solomd-mcp-4.14.11.mcpb

### What are the best alternatives to SoloMD?

The closest alternatives to SoloMD are Codebase Memory, XERJ, Ha MCP, Claude Code Ultimate Guide and Nautilus Compass Memory.

## Alternatives

- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.

---
Source: https://ai-powered.com/mcp/solomd
