Monet MCP Server
README.md
# Monet
**One brain for you and your agents.**
A quiet, local-first Markdown vault: a rich desktop app for you, and a CLI
and MCP server for your agents. Your notes stay as plain `.md` files in a
folder you own.
[](https://github.com/felipebarcelospro/monet/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org)
[](CONTRIBUTING.md)
Monet stores notes as plain `.md` files in a folder you own. Links are
`[[wikilinks]]`, backlinks are indexed automatically, attachments resolve
relative to the vault, and the same folder serves the desktop app, the
command line and AI agents — with no proprietary database in between. One
vault, one engine, two ways in:
| For you | For your agents |
|---|---|
| A quiet desktop app: rich Markdown editor, interactive graph, backlinks, search, command palette. | A CLI and an MCP server driving the same engine: search, read, create and link notes on your behalf. |
### Why Monet
| You may know… | What it gives you | What Monet does instead |
|---|---|---|
| A notes app with an agent pack bolted on | An app for people; agents get prompts. | Agents drive the same engine, with schemas and MCP tools — one brain, not two tools sharing a folder. |
| A cloud AI notebook | Your brain lives on someone else's servers. | Monet is local-first: the folder is yours, offline included. |
| Prompt and skill packs | Instructions without an engine. | Monet ships the engine: indexing, search, backlinks and safe writes underneath. |
## Install the CLI
**macOS and Linux:**
```sh
curl -fsSL https://github.com/felipebarcelospro/monet/releases/latest/download/install.sh | sh
```
**Windows (PowerShell):**
```powershell
irm https://github.com/felipebarcelospro/monet/releases/latest/download/install.ps1 | iex
```
The installer picks the right build for your system, verifies the SHA-256
checksum and installs to `~/.local/bin` — no Node.js needed. Set
`MONET_INSTALL_DIR` to install somewhere else.
**Homebrew:**
```sh
brew install felipebarcelospro/tap/monet
```
**npm** (any platform, needs Node ≥ 22):
```sh
npm install -g @monet-ai/cli
```
Then point it at your notes:
```sh
monet vault use ~/Documents/Vault
monet vault current
monet note list
```
---
## Contents
- [Why Monet](#why-monet)
- [Features](#features)
- [Screenshots](#screenshots)
- [Requirements](#requirements)
- [Install](#install-the-cli)
- [Build from source](#build-from-source)
- [Monorepo structure](#monorepo-structure)
- [For you: the desktop app](#for-you-the-desktop-app)
- [For your agents: CLI and MCP](#for-your-agents-cli-and-mcp)
- [The vault format](#the-vault-format)
- [Markdown support](#markdown-support)
- [Architecture](#architecture)
- [Testing](#testing)
- [Contributing](#contributing)
- [Security](#security)
- [License](#license)
---
## Features
| | |
|---|---|
| **Local-first vault** | Plain Markdown files in any folder. YAML frontmatter, `[[wikilinks]]`, `![[embeds]]`, `#tags` and aliases. Link resolution follows Obsidian rules: case-insensitive, optional `.md`, aliases, and closest-folder tie breaking. |
| **Rich Markdown** | Tables, task lists, footnotes, images, video, audio, file attachments, Mermaid diagrams, KaTeX math, syntax-highlighted code, callouts and raw HTML. `⌘E` toggles a full reading view. |
| **Live editor** | CodeMirror 6 with tables, media, diagrams, display math and note embeds rendered in place; clicking a block returns to its Markdown. Task boxes are clickable. |
| **Interactive graph** | Deterministic force-directed graph with tag filtering, degree-based node sizing, hover inspection, pan and zoom. |
| **Command line interface** | Notes, search, backlinks, links, tags, the graph and vault switching. Local snapshots with `monet backup`. Human-readable output or `--format json` for scripts. |
| **MCP server for agents** | Exposes the vault to Claude Code, Cursor, Windsurf, Codex and any MCP client. Agents can search, read, create and link notes. |
| **Three languages** | English, Brazilian Portuguese and Spanish across the app and the CLI. |
| **Cross-platform** | Electron on macOS, Linux and Windows, with a native-feeling frameless window. |
---
## Screenshots
| Editor | Reading view |
|---|---|
|  |  |
| Graph | Command palette |
|---|---|
|  |  |
| Settings | Welcome |
|---|---|
|  |  |
---
## Requirements
- **Node.js** 22 or later
- **pnpm** 11 or later
- **macOS**, **Linux** or **Windows**
- **Bun** (optional) — only to build the standalone CLI binaries
The app is developed and tested on macOS first; the other platforms use the
same Electron, Vite and Node code paths.
---
## Build from source
```sh
# 1. Install the workspace.
pnpm install
# 2. Create a deterministic demo vault in ExampleVault/.
pnpm seed
# 3. Run the desktop app with hot reload.
pnpm dev -- --vault ExampleVault
```
The app opens on the note you last edited. To use your own folder, press
`⌘O` (or `Ctrl+O`) and choose it, or run `monet vault use <path>` from the CLI.
### Build a desktop bundle
```sh
pnpm package
# macOS: build/Monet.app
# Linux: build/app
# Windows: build/app
```
The bundle is unsigned. On macOS, Gatekeeper asks for confirmation the first
time you open it.
### Run from source
```sh
pnpm --filter @monet/cli build
cd packages/cli && pnpm link --global
monet vault current
monet note list
```
---
## Monorepo structure
| Package | What it is |
|---|---|
| **`@monet/core`** (`packages/core`) | Pure TypeScript engine: vault scanning, frontmatter, wikilinks, index, backlinks, search, graph, safe writes. Node and browser entry points. |
| **`@monet/cli`** (`packages/cli`) | The `monet` CLI and MCP server — your agents' way into the vault. Built with [Incur](https://github.com/wevm/incur) so commands, schemas, completions, MCP tools and agent skills all come from one declaration. |
| **`@monet/app`** (`packages/app`) | Desktop application: Electron main process, preload bridge and React 19 renderer with CodeMirror 6. |
### Common scripts
```sh
pnpm dev # Desktop app with hot reload
pnpm dev:cli # CLI from source
pnpm build # Build core, CLI and app
pnpm package # Package the desktop app
pnpm test # Vitest across all packages
pnpm typecheck # TypeScript across all packages
pnpm lint # Biome lint
pnpm format:check # Biome formatting check
pnpm seed # Seed ExampleVault/
pnpm screenshots # Refresh docs/screenshots/
```
---
## The vault format
A vault is an ordinary folder. Monet never rewrites a file it did not have to
touch, and everything it writes is plain Markdown.
```markdown
---
title: Release Plan
tags: [project, release]
aliases: [Plan]
---
# Release Plan
The release ships on Friday. See [[Design Notes]] and ![[Checklist]].
Tagged #project and #area/product.
```
- **Wikilinks** — `[[Note]]`, `[[Note|display text]]`, `[[Note#Heading]]`, `[[#Heading]]`.
- **Embeds** — `![[Note]]`, `![[image.png]]`, `![[report.pdf]]`.
- **Tags** — `#tag`, `#nested/tag`, or a `tags` list in the frontmatter.
- **Aliases** — `alias` or `aliases` in the frontmatter.
Notes are indexed on open and on change; the index is derived state, never a
second source of truth.
---
## Markdown support
| Syntax | Renders as |
|---|---|
| A pipe table (GFM) | A bordered table with aligned columns and horizontal scroll. |
| `- [ ]` / `- [x]` | A task list; boxes are clickable in the editor. |
| `**bold**`, `*italic*`, `~~struck~~`, `` `code` `` | Inline formatting. |
| `[[Note]]`, `[[Note\|label]]` | An internal link that opens the note. |
| `![[Note]]` | The note itself, embedded one level deep. |
| `![[image.png]]`, `` | The image, resolved relative to the note or anywhere in the vault. |
| `` | A video player; mp3, wav, m4a and flac play inline too. |
| `![[report.pdf]]` | A file card that opens the attachment in its own app. |
| A `mermaid` fence | Flowchart, sequence, class, state, ER or gantt diagram. |
| `$…$`, `$$…$$` | KaTeX math, inline and display. |
| A `ts` fence | Syntax-highlighted code with a language label. |
| `[^1]` | GFM footnotes with a backlink. |
| `> [!note]` | A callout: note, tip, warning, caution, important, quote and friends. |
| `<details>`, `<kbd>`, raw HTML | Passed through, for what Markdown cannot express. |
Tables, media, diagrams, display math, callouts and embeds are rendered in
place while the cursor is elsewhere; clicking the block puts the cursor back
in the Markdown. `⌘E` opens the reading view, where the whole note is rendered
at once.
Raw HTML is rendered as written. A vault is trusted input: only open notes and
vaults you trust. See [SECURITY.md](SECURITY.md).
---
## For you: the desktop app
A quiet place to think. Three columns, a rich editor, and the whole vault as
a graph — no cloud, no account, just a folder.
### Download
Prebuilt installers are attached to each
[release](https://github.com/felipebarcelospro/monet/releases/latest):
| Platform | File |
|---|---|
| macOS (Apple silicon) | `Monet-<version>-arm64-mac.dmg` |
| macOS (Intel) | `Monet-<version>-x64-mac.dmg` |
| Windows | `Monet-<version>-x64-win.exe` |
| Linux | `Monet-<version>-<arch>-linux.AppImage` |
The desktop app is also on Homebrew:
```sh
brew install --cask felipebarcelospro/tap/monet
```
The builds are **not signed**. On macOS, right-click the app and choose
**Open** the first time (or use *System Settings → Privacy & Security → Open
Anyway*). On Windows, SmartScreen offers *More info → Run anyway*. Nothing is
hidden about it — the installers are produced from this repository by the
Desktop Release workflow, and building from source is always an option.
### Features
- **Three columns** — sidebar (folders, tags, favourites), note list, editor,
with an inspector for properties, backlinks, outgoing links and the outline.
- **Editor** — CodeMirror 6, wikilink autocomplete, live blocks, dirty-state
aware saving, per-note history, favourites and reading time.
- **Reading view** — `⌘E`, or the book button, renders the note with editorial
typography, tables, media, diagrams, math and embeds.
- **Graph** — the whole vault as a deterministic force-directed canvas. Filter
by tag, click a node to open the note.
- **Command palette** — `⌘K`, plus `⌘P` for the quick switcher.
- **Inspector** — metadata, aliases, tags, word count, reading time, backlinks,
outgoing links and the document outline.
- **Preferences** — theme, locale, sort order, editor width and body font.
- **Welcome** — create a vault or open an existing folder; recent vaults are
remembered.
Keyboard shortcuts follow macOS conventions with `Ctrl` on Linux and Windows.
---
## For your agents: CLI and MCP
The CLI and the MCP server are how agents reach the same brain. Both are
clients of the engine the app uses — an agent sees exactly what you see,
because it is the same folder, the same index, the same rules.
### The command line
```sh
# Notes
monet note new "Release Plan" --folder Projects --tag project
monet note list --tag project
monet note show "Release Plan" --links
monet note edit "Release Plan" --append "Ship on Friday."
monet note move "Release Plan" --to "Archive/Release Plan"
monet note delete "Release Plan" --yes
# Search, links and the graph
monet search "release" --limit 20
monet backlinks "Design Notes"
monet link create "Checklist" --target "Design Notes"
monet graph --format json
monet tags
# Vaults and safety
monet vault use ~/Documents/Vault
monet vault current
monet vault list
monet backup # snapshot outside the vault
monet open
```
Every command accepts `--format toon|json|yaml|md|jsonl`. The default is TOON,
compact for agents; use `--format json` for programs.
### Search
Search is local and dependency-free. It folds accents (`reuniao` finds
`Reunião`), matches every word of a multi-word query in any order, falls back
to a fuzzy title match, and returns an excerpt around the first body hit.
Exact and prefix titles rank above aliases, tags and body text.
Embeddings are not part of this release: there is no model download, no vector
database and no network call. Semantic and related-note search are on the
roadmap, behind the same `search` surface.
### Backups
A vault is a plain folder, and `monet backup` writes a local snapshot without
touching the original:
```sh
monet backup # ~/.local/share/monet/backups
monet backup --keep 30 # keep the last 30 snapshots
monet backup --output ~/Backups # choose the destination
```
Git, Time Machine or any folder synchroniser work too; the vault has no
proprietary database. `.git`, `node_modules`, `dist`, `build` and the app lock
are skipped in a snapshot.
### Choosing the vault
Monet is designed around one vault. Point the CLI at it once:
```sh
monet vault use ~/Documents/Vault
```
That writes the shared configuration (`~/.config/monet/config.json`) — the same
file the app reads — and remembers the folder. From then on every command
works without `--vault`:
```sh
monet note list
monet search "release"
monet graph --format json
```
`monet vault current` shows the path in use, where it came from and how many
notes it holds. `monet vault list` shows the current vault and the ones opened
recently, including folders that no longer exist.
The resolution order is: `--vault`, `MONET_VAULT`, the configured vault, then
the current directory. An MCP server can be pinned with `MONET_VAULT`, while an
interactive terminal can switch with `monet vault use`. The app follows the
same configuration, so `monet open` and the next launch of the window use the
same folder.
---
### The MCP server
Monet speaks the Model Context Protocol over stdio:
```sh
monet --mcp # Start the MCP server
monet mcp add # Register it with the MCP clients it finds
monet skills add # Install generated skills for supported agents
monet mcp doctor # Validate startup and tool listing
```
Tools exposed to agents include `search`, `note_show`, `note_new`, `note_list`,
`backlinks`, `graph`, `link_create`, `vault_list`, `vault_current` and
`vault_use`. The server uses the configured vault, so an agent sees the same
folder as the app.
To pin a server to a vault without changing the global configuration:
```sh
MONET_VAULT=~/Documents/Vault monet --mcp
```
There is no hand-written skill to keep in sync. `monet skills add` generates
what agents need from the same command declarations that power the CLI, so
the guidance always matches the tool. The one habit it teaches: run
`monet vault current` before reading or writing, and never guess a path.
---
## Architecture
Monet is three packages around one engine. The app and the CLI are both
clients of `@monet/core`; the renderer never touches the disk directly.
```
Electron main ── IPC ── preload ── React renderer
│ │
└──────── @monet/core ──────────┘
│
Markdown files
```
Read [ARCHITECTURE.md](ARCHITECTURE.md) for the IPC contract, the `monet://`
asset protocol, the Markdown pipeline, the index and the save model.
---
## Testing
```sh
pnpm test
```
Vitest runs across `@monet/core`, `@monet/cli` and `@monet/app`. The parser
contract is verified against the fixtures in `Fixtures/`, and the app tests
cover the vault service, target resolution and link handling.
```sh
pnpm typecheck
pnpm lint
pnpm format:check
```
CI runs all of them on every push and pull request.
---
## Contributing
Contributions are welcome — code, docs, translations, bug reports and
screenshots. Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup, workflow and
the review checklist, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for the
community rules.
Good first issues are labelled `good first issue`. If you are unsure where a
change belongs, open a discussion or an issue before writing code.
---
## Security
Please do not open a public issue for a vulnerability. Use GitHub's private
vulnerability reporting (Security → Advisories) and read
[SECURITY.md](SECURITY.md) for the scope and the trust model.
---
## License
MIT © Monet contributors. See [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues