zennotes-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zennotes-mcp search my notes for 'project roadmap'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
zennotes-mcp
MCP server that connects AI agents to a self-hosted ZenNotes vault. It wraps the complete HTTP API of the ZenNotes Go server and exposes it as typed MCP tools, so agents can read, search, create and organize notes directly.
Features
65 tools covering the whole vault API:
vault: info, settings, server-side directory browser
notes: list, read, write, create, rename, move, duplicate, trash, restore, archive, plus
capture,appendandprependhelperssearch: full-text search, search capabilities
tasks: vault-wide aggregation or per note
folders: create, rename, delete, duplicate
assets: list, upload, download, rename, move, duplicate, delete, plus the deleted-assets trash (list, restore, purge)
templates and workflows: full CRUD, workflow runs (apply, undo, history)
comments, Excalidraw drawings, demo tour, session management
Related MCP server: Obsidian MCP Server
Requirements
Python 3.10+
A running ZenNotes server (local
zennotes-server, Docker imageadibhanna/zennotes, or any remote deployment)
Install
From source:
pip install -e .Or directly from GitHub:
pip install git+https://github.com/PacomeKFP/zennotes-mcp.gitThis provides the zennotes-mcp command.
Configuration
Everything goes through environment variables. Nothing personal is hardcoded.
Variable | Required | Default | Description |
| no |
| Base URL of the ZenNotes server |
| for protected routes | empty | Bearer token of the server |
cp .env.example .env # then fill in your values
export ZENNOTES_URL="http://127.0.0.1:7878" # or your remote URL
export ZENNOTES_AUTH_TOKEN="your-token-here"Public routes (health_check, get_version, get_capabilities, ...) work
without a token. Everything else returns HTTP 401 until the token is set.
Run
Stdio mode (for agents):
zennotes-mcpConnect an agent
OpenCode v1 (~/.config/opencode/opencode.jsonc):
{
"mcp": {
"zennotes": {
"type": "local",
"command": ["zennotes-mcp"],
"environment": {
"ZENNOTES_URL": "http://127.0.0.1:7878",
"ZENNOTES_AUTH_TOKEN": "your-token-here"
},
"enabled": true
}
}
}OpenCode v2 moves the same block under mcp.servers (see
opencode.json.example). The same stdio command also works in Claude Code,
Claude Desktop and Codex. Restart the agent after editing the config, as MCP
servers connect at startup.
Examples
Once connected, just ask:
"with zennotes, list my notes"
"find my notes about backups and summarize them in a new note"
"capture this in my quick notes: ..."
Development
pip install -e .
python tests/test_smoke.py # public endpoints, no token neededZENNOTES_URL can point at a remote server for the smoke test:
ZENNOTES_URL="https://my-server.example.com" python tests/test_smoke.pySecurity
The auth token only ever lives in environment variables or your local agent config. Never commit it:
.envis git-ignored.Prefer read-only prompts for shared agents, and keep
delete,empty_trashandsession_rotate_tokenfor supervised use.
Roadmap
Progressive updates following ZenNotes releases: tags endpoint if re-exposed, real-time watch events, batch operations.
Available Tools
65 toolsall_tasksC
Toutes les taches agregees du vault.
Inputs: include_excluded. Returns: result
append_to_noteB
Ajoute du texte a la fin d'une note.
Inputs: path (required), text (required). Returns: result
apply_workflowC
Applique un run de workflow prepare (workflowId, ops, changes...).
Inputs: prepared_run (required). Returns: result
archive_noteC
Archive une note.
Inputs: path (required). Returns: result
assets_existsB
Dit si le dossier assets existe.
Inputs: no named parameters. Returns: result
browse_directoriesB
Explore les dossiers cote serveur (vault picker).
Inputs: path. Returns: result
capture_noteB
Capture rapide : cree une note puis y ecrit le body si fourni.
Inputs: title (required), body, folder. Returns: result
create_excalidrawC
Cree un dessin Excalidraw.
Inputs: title, folder, subpath. Returns: result
create_folderC
Cree un dossier. folder = inbox|quick|archive|trash.
Inputs: folder (required), subpath. Returns: result
create_noteC
Cree une note. folder = inbox|quick|archive|trash.
Inputs: title, folder, subpath. Returns: result
delete_assetA
Supprime un asset (corbeille assets, restaurable).
Inputs: path (required). Returns: result
delete_folderD
Supprime un dossier.
Inputs: folder (required), subpath. Returns: result
delete_noteA
Supprime definitivement une note (non restaurable).
Inputs: path (required). Returns: result
delete_templateC
Supprime un template.
Inputs: source_path (required). Returns: result
delete_workflowC
Supprime un workflow.
Inputs: source_path (required). Returns: result
delete_workflow_runsB
Supprime l'historique des runs d'un workflow.
Inputs: workflow_id (required). Returns: result
demo_generateB
Genere la visite demo dans le vault.
Inputs: no named parameters. Returns: result
demo_removeC
Retire la visite demo du vault.
Inputs: no named parameters. Returns: result
download_assetB
Telecharge un asset vers un chemin local.
Inputs: path (required), local_path (required). Returns: result
duplicate_assetC
Duplique un asset.
Inputs: path (required). Returns: result
duplicate_folderC
Duplique un dossier.
Inputs: folder (required), subpath. Returns: result
duplicate_noteC
Duplique une note.
Inputs: path (required). Returns: result
empty_deleted_assetsA
Vide la corbeille des assets.
Inputs: no named parameters. Returns: result
empty_trashB
Vide la corbeille.
Inputs: no named parameters. Returns: result
get_capabilitiesB
Capacites annoncees par le serveur (watch, templates, workflows...).
Inputs: no named parameters. Returns: result
get_platformB
Plateforme hote du serveur.
Inputs: no named parameters. Returns: result
get_search_capabilitiesB
Moteur de recherche dispo (ripgrep / fzf).
Inputs: no named parameters. Returns: result
get_vault_settingsA
Lit les reglages du vault (dossiers systeme, daily notes, taches...).
Inputs: no named parameters. Returns: result
get_versionB
Version du serveur + runtime Go.
Inputs: no named parameters. Returns: result
health_checkA
Ping le serveur (GET /api/healthz). Pas d'auth requise.
Inputs: no named parameters. Returns: result
list_assetsB
Liste les pieces jointes.
Inputs: no named parameters. Returns: result
list_deleted_assetsC
Assets supprimes (restaurables).
Inputs: no named parameters. Returns: result
list_foldersB
Liste les dossiers du vault.
Inputs: no named parameters. Returns: result
list_notesB
Liste toutes les notes (metadonnees).
Inputs: no named parameters. Returns: result
list_templatesA
Liste les templates custom (.zennotes/templates).
Inputs: no named parameters. Returns: result
list_workflow_runsB
Historique des runs de workflows.
Inputs: no named parameters. Returns: result
list_workflowsB
Liste les workflows.
Inputs: no named parameters. Returns: result
move_assetC
Deplace un asset.
Inputs: path (required), target_dir (required). Returns: result
move_noteC
Deplace une note vers un autre dossier.
Inputs: path (required), target_folder (required), target_subpath. Returns: result
prepend_to_noteB
Ajoute du texte au debut d'une note.
Inputs: path (required), text (required). Returns: result
purge_deleted_assetA
Purge definitivement un asset supprime.
Inputs: undo_token (required). Returns: result
read_commentsB
Lit les commentaires d'une note.
Inputs: path (required). Returns: result
read_noteB
Lit une note (body markdown + frontmatter). Ex: 'Bienvenue.md'.
Inputs: path (required). Returns: result
read_templateA
Lit un template. Ex: '.zennotes/templates/adr.md'.
Inputs: path (required). Returns: result
rename_assetC
Renomme un asset.
Inputs: name (required), path (required). Returns: result
rename_folderC
Renomme un sous-dossier.
Inputs: folder (required), new_subpath (required), old_subpath (required). Returns: result
rename_noteB
Renomme une note (les [[wikilinks]] suivent automatiquement).
Inputs: path (required), title (required). Returns: result
restore_deleted_assetB
Restaure un asset supprime (passer l'objet deleted tel quel).
Inputs: deleted (required). Returns: result
restore_noteB
Restaure une note depuis la corbeille.
Inputs: path (required). Returns: result
search_textA
Recherche plein-texte dans le vault (matches par ligne).
Inputs: query (required). Returns: result
session_loginA
Ouvre une session navigateur via le token bootstrap.
Inputs: token (required). Returns: result
session_logoutA
Ferme la session courante.
Inputs: no named parameters. Returns: result
session_rotate_tokenA
Regenere le token d'auth (ATTENTION : invalide l'ancien).
Inputs: no named parameters. Returns: result
session_statusB
Etat de session (auth requise ou non).
Inputs: no named parameters. Returns: result
set_vault_settingsC
Ecrit les reglages du vault (passer l'objet settings complet).
Inputs: settings (required). Returns: result
tasks_forC
Taches d'une note donnee.
Inputs: path (required), include_excluded. Returns: result
trash_noteA
Met une note a la corbeille (restaurable).
Inputs: path (required). Returns: result
unarchive_noteC
Sort une note de l'archive.
Inputs: path (required). Returns: result
undo_workflow_runC
Annule un run de workflow.
Inputs: run_id (required). Returns: result
upload_assetB
Upload un fichier local comme asset, optionnellement lie a une note.
Inputs: local_path (required), note_path. Returns: result
vault_infoB
Infos vault : racine + nom.
Inputs: no named parameters. Returns: result
write_commentsC
Ecrit les commentaires d'une note (liste d'objets commentaire).
Inputs: path (required), comments (required). Returns: result
write_noteA
Ecrase le contenu d'une note existante.
Inputs: body (required), path (required). Returns: result
write_templateC
Cree ou edite un template.
Inputs: raw (required), slug (required), previous_source_path. Returns: result
write_workflowC
Cree ou edite un workflow.
Inputs: raw (required), slug (required), previous_source_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 65 tools
Most tools map to a clear resource/action pair (list_notes, rename_asset, delete_workflow). A few boundary cases could be confused—create_note, write_note, and capture_note all write note content with subtly different semantics—and browse_directories may be mistaken for list_folders, but descriptions mostly clarify intent.
The dominant verb_noun snake_case pattern is readable and predictable, e.g., list_notes, create_folder, restore_deleted_asset. There are minor exceptions like session_status, vault_info, assets_exists, and demo_generate, but they do not obscure the overall convention.
With 65 tools, this server far exceeds even the 25+ threshold and crosses the 50+ extreme mismatch threshold. No matter how broad ZenNotes is, this many endpoints overwhelms an agent's tool-selection space and context window.
The tool surface covers the full lifecycle for notes, folders, assets, templates, and workflows, including soft-delete/restore and permanent delete paths. Session management, search, tasks, comments, and demo utilities are also present, leaving no major workflow dead ends.
Maintenance
Related MCP Connectors
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Read and write the notes and folders of your Grape account, the AI note-taking app.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Related MCP Servers
- AlicenseAqualityDmaintenanceConnects to Obsidian vaults via the Local REST API plugin, enabling AI-assisted Zettelkasten workflows including creating atomic notes, searching content, managing links and tags, and performing precise content editing operations.13MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to search, create, and manage notes in an Obsidian vault via 40+ local tools.5214 npmMIT
- AlicenseAqualityBmaintenanceProvides an AI agent with a searchable markdown notes vault, offering tools to create, read, list, search, update, and delete notes stored as plain .md files.6MIT
- AlicenseNot gradedqualityDmaintenanceEnables agents to search, read, and write notes in an Obsidian vault, including creating and updating notes in an inbox and syncing changes with Gitea/GitHub.MIT