MCP server (AI agents)

LightNote includes a headless MCP (Model Context Protocol) server that turns your workspace into a tool for AI agents (Claude Desktop, Claude Code, Cursor, and any MCP-speaking client). The agent can read and write files, search, query tabular data and databases, work with the tasks, use Git and fire HTTP requests — everything confined to the folder (directory jail: paths with .. or outside the root are refused). The transport is JSON-RPC 2.0 over stdin/stdout; each session spins up a lightweight lnote.exe process, separate from the editor window.

One-click shortcut: AI → Enable AI in this folder turns on MCP and writes the .mcp.json in one go (the click is the consent). If AI is already active in the folder, the item becomes Configure AI in this folder… and opens Workspace settings.

Two layers of safety: (1) the server only starts if you have opted in for that folder; (2) every tool is locked to the workspace root. On top of that, each tool is announced with annotations (read-only, destructive, idempotent, "touches the outside world") so the AI client can assess the risk before calling it.

Step-by-step setup

1. Enable MCP for the folder. In Tools → Workspace → Workspace settings..., check Enable MCP for this workspace. Without this opt-in the server refuses to start (it's the main gate). Alternatively, from the command line: lnote --mcp-enable "C:\Path\to\workspace" (and --mcp-disable to turn it off).
2. Find the path to lnote.exe. It lives in the same folder as lightnote.exe (the app's install folder). It's the "slim" console executable, no UI — this is what the agent runs.
3. Register the server in your AI client, pointing the command at lnote.exe and passing --mcp followed by the workspace folder. In the format used by Claude Desktop / Cursor and the like:

{
  "mcpServers": {
    "lightnote": {
      "command": "C:\\Path\\to\\lnote.exe",
      "args": ["--mcp", "C:\\Path\\to\\workspace"]
    }
  }
}

Configuration tips:

• Backslashes in JSON must be doubled (C:\\Users\\...\\lnote.exe), as in the example.
• To expose several workspaces, add one entry per folder, with distinct names ("lightnote-projectA", "lightnote-projectB"), each pointing at its own root.
• After saving the configuration, restart the AI client so it starts the server. Once connected, the agent should list the lightnote_* tools; ask it to "list the workspace files" to confirm it works.
• For Claude Code (CLI), the same server can be registered with claude mcp add lightnote -- "C:\Path\to\lnote.exe" --mcp "C:\Path\to\workspace".

Database password (optional). The db_query tool opens a .lnc connection. If the password is encrypted with the Passphrase, pass the phrase via the LNOTE_PASSPHRASE environment variable in the server block (never in command-line arguments) — connections whose password is in "ask" mode can't be used unattended.

With LightNote open, the database goes through the window. An AI CLI running in the app's terminal (Claude Code, for example) queries through the session you already opened: this works for any database, including Oracle, with the password already typed and the SSH tunnel up. If the connection is closed, the password is asked in the window — declining there declines the AI —, and the status bar tells you when an AI tool runs a query. To write a query against a large database, the AI finds tables by name with db_search_objects (across all schemas), reads the list with the comment and estimated rows (db_list_objects), and describes several tables at once, with the foreign keys that give the JOINs (db_describe). With the app closed, the above applies.

AI queries are opt-in per connection. Enabling MCP in the folder does not expose the connections: each .lnc only answers db_query when “Allow AI queries (MCP)” is checked in the connection dialog. Access is read-only (SELECT). The permission is kept in the folder settings, on this machine: it is not stored in the .lnc file nor carried by Git, and the AI cannot turn it on by editing the file. Changing the connection's server, database, user or tunnel suspends it until you check the option again. A file database (SQLite, DuckDB) must be inside the workspace, and through DuckDB the AI reads only files inside the workspace — none at all while LightNote is open.

Exporting from the database via the agent. Besides querying, the agent can materialize a SELECT into a file with db_export (Parquet, CSV, JSON or .xlsx) — useful for results too large to fit in a reply. The same three safeguards apply, in this order: the query must be read-only, the connection needs the «Allow AI queries (MCP)» opt-in (checked before the password is decrypted), and the destination must stay inside the workspace. Large exports use the system temp folder as scratch space, roughly the size of the result — keep disk space free.

Available tools

The agent sees the tools under the client's prefix (e.g. lightnote_read_file). By category:

• Files: read_file (with optional line range), write_file, edit_file (replaces an exact snippet, without rewriting the whole file), append_file, list_files, move_file, make_dir and delete_file (goes to the Recycle Bin, not a hard delete).
• Search and navigation: search_files (ripgrep, with subfolder/glob filter and limit), list_symbols (outline of a file's functions/classes) and open_in_editor (opens/focuses a file in the LightNote window, if it's open).
• Data and SQL: query (DuckDB SQL over Parquet/CSV/JSON, tsv/json/markdown output), describe_table (schema + statistics, without dumping rows), export_query (materializes a SELECT into a file via COPY), sqlite_query (SQL on a .sqlite/.db), db_list_connections (lists the workspace's .lnc files) and db_query (read-only SQL on a .lnc connection). To send the result to a file instead of the reply, db_export (Parquet/CSV/JSON/.xlsx).
• Also: search_notes (retrieves the most relevant note snippets for a question — the same engine as AI Chat), list_links (a note's outgoing links, resolved or broken), audit_vault_links (broken links and orphan notes across the vault), list_note_templates and the template parameter of create_note, list_due_tasks (tasks due today or overdue across all projects), xlsx_read (reads an .xlsx sheet as TSV), data_diff (compares two tabular files) and the database catalog db_list_objects/db_describe (tables/views and a table's columns, keys and DDL — same requirements as db_query). And note_export (exports a note to docx, odt, epub, LaTeX, Typst, HTML, reStructuredText, AsciiDoc, Org, MediaWiki, Notebook or another Markdown dialect — with no window at all, and also from lnote note-export). And note_import (the reverse: a docx, odt, epub, rtf, HTML or tex file becomes a note next to the original, with headings, lists, tables, emphasis, links, equations and images — also from lnote note-import). And folder_export (a whole folder becomes an HTML site, a set of documents or Markdown, with the links rewritten — also from lnote folder-export).
• Archives: zip_list (lists the members of a .zip/.isx) and zip_read (reads a member as text) — without extracting the archive to disk.
• Tasks: list_task_projects (lists the workspace's .lnt task projects), list_tasks, list_task_statuses (board columns), create_task, update_task (title, effort, column, priority, dates, %, tags, checklist and archive), update_task_status (move between columns), delete_task and task_note (read/write the task's .md note). A workspace may hold several .lnt projects: pick one with the project parameter (the name returned by list_task_projects; optional when there is only one). The id/status_id are session identifiers — do not read the internal .lnt files to obtain them; use the task tools.
• Notes (PKM): create_note (create a .md note), append_daily_note (append a capture to today's note), remember (stores one durable fact about you in the memory note), list_backlinks (notes pointing to a note), list_note_tags and search_by_tag (the vault #hashtags and the notes using them) and add_task (create a task with due date/tags, accepting natural language in the title).
• Git: git_status, git_log, git_diff and git_restore.
• Web and alerts: http_request (fires an HTTP request and returns status/headers/body) and notify (shows a tray notification on the open window — handy for the agent to signal it's done).
• AI proxy: list_ai_models and ask_ai (below).
• LightNote itself: help_lookup (reads this Help by section or by term, in the requested language) and markdown_reference (the exact syntax of the Markdown the app renders). On connecting, the client also gets a description of the server with the tools by category, and the Help and the Markdown reference show up as resources (lightnote://help/… and lightnote://markdown/…).

The server also exposes the workspace files as MCP resources (resources/list and resources/read), for clients that prefer to "attach" files instead of calling read_file.

Your Prompt library (the workspace's Prompts/ folder) is exposed as MCP prompts (prompts/list and prompts/get). In Claude Code each prompt becomes a slash command — /mcp__lightnote__<name> — ready to use inside the AI CLI.

Write safety net. Before overwriting (write_file/edit_file) or removing (delete_file) a file, the server saves the previous version to the Local History — the editor's own safety net — so you can undo a change made by an agent even outside a Git repository.

Each tool declares whether it reads or writes: besides the MCP annotations (readOnlyHint/destructiveHint), the description starts with a [read-only], [writes] or [destructive] badge — handy for building allowlists safely.

AI proxy (delegate to another model)

The API providers you registered with the MCP column checked are exposed to the agent through two tools: list_ai_models (lists the allowed models, with id, name and model) and ask_ai ({model, prompt}). This lets the main agent delegate a sub-task to a cheaper or specialized model. The call is brokered by the running LightNote (the MCP's lnote.exe forwards the request to the app window over the internal bridge): the API key never leaves your machine and never reaches the agent. If LightNote isn't open, the tool returns an error asking you to open it.