Skip to main content
Glama
zennotes-mcp

zennotes-mcp

by PacomeKFP

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, append and prepend helpers

  • search: 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 image adibhanna/zennotes, or any remote deployment)

Install

From source:

pip install -e .

Or directly from GitHub:

pip install git+https://github.com/PacomeKFP/zennotes-mcp.git

This provides the zennotes-mcp command.

Configuration

Everything goes through environment variables. Nothing personal is hardcoded.

Variable

Required

Default

Description

ZENNOTES_URL

no

http://127.0.0.1:7878

Base URL of the ZenNotes server

ZENNOTES_AUTH_TOKEN

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-mcp

Connect 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 needed

ZENNOTES_URL can point at a remote server for the smoke test:

ZENNOTES_URL="https://my-server.example.com" python tests/test_smoke.py

Security

  • The auth token only ever lives in environment variables or your local agent config. Never commit it: .env is git-ignored.

  • Prefer read-only prompts for shared agents, and keep delete, empty_trash and session_rotate_token for supervised use.

Roadmap

Progressive updates following ZenNotes releases: tags endpoint if re-exposed, real-time watch events, batch operations.

Available Tools

65 tools
all_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

    C2.9/5.0

    Scored across 65 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers