Hillnote Logo

Hillnote Local MCP Server

Connect AI assistants to the Hillnote workspaces on your own machine. The Hillnote desktop app bundles a local Model Context Protocol (MCP) server that lets Claude Desktop, Cursor, and other MCP-compatible clients search, read, and edit your workspace files directly — no sync, no sign-in, no data leaving your computer.

At a glance

RunsLocally, on your machine, alongside the Hillnote desktop app
Transportstdio (the client launches the server as a local process)
AuthenticationNone — it operates on files you already own, with your OS permissions
What it reachesYour local Hillnote workspaces, discovered automatically from the app
NetworkLocal only — its one connection is to the Hillnote app on the same computer, never the internet

Local vs. remote. This is the local server. Hillnote also offers a remote MCP server at https://hillnote.com/mcp that works over the internet with OAuth sign-in and reaches your synced workspaces. Use the local server when you want zero-setup, offline access to the files on your own computer; use the remote server when you want any client, anywhere, to reach your synced workspaces.

What you can do

Once connected, your assistant can work with your local workspace the way you do:

  • Ask questions about your notes. Search across filenames, titles, headings, tags, and content with smart fuzzy ranking, then read the documents that matter.
  • Create and edit documents. Draft new notes, insert or rewrite sections, find-and-replace, rename, and delete — the assistant edits the same markdown files you see in the app.
  • Build slide decks. Hillnote's .slides.md format turns markdown into presentations; the assistant follows built-in authoring guides to write the story first, then style it.
  • Build moodboards. Pin images, notes, links, videos, and colour swatches to a moodboard (.moodboard.md), grouped in frames and joined by connectors.
  • Work with databases. Create databases, add and update rows and columns, and set up views — all stored as markdown on disk.
  • Use and manage recipes. Recipes are saved prompt templates with reference documents; assistants can run them, create new ones, and keep them up to date.
  • Create HTML tools. Ask for a calculator, tracker, or visualization and the assistant builds a self-contained mini-app right in your workspace.

Requirements

  • The Hillnote desktop app for Mac or Windows, installed (it ships the MCP server inside the app).
  • An MCP-compatible client — Claude Desktop, Claude Code, Cursor, VS Code (Copilot), etc.

There's nothing else to install. The server runs on the Hillnote app itself, so you don't need Node.js.

Connect your assistant

The easiest path is to let the Hillnote app configure your client for you.

  1. Open Hillnote and go to Settings → Connections, then open the Local MCP card.
  2. Under CONNECT AN AGENT APP, find your client. Apps found on this computer show Detected and come first.
  3. Click Configure. Hillnote shows the exact change it will make to your client's config file, pre-filled with the correct paths to the bundled server. You can edit it first.
  4. Click Save Configuration. Hillnote writes it to the config file for you.
  5. Fully quit and reopen your client — MCP servers are only picked up on a fresh start.
  6. Start a chat and ask it to "list my Hillnote workspaces" to confirm everything is wired up.
The CONNECT AN AGENT APP grid on the Local MCP card: Claude Desktop shows Configured with Reconfigure, while Claude Code, Cursor, VS Code (Copilot), Gemini CLI and Codex CLI show Detected with Configure.

The grid covers Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (Copilot), Gemini CLI, Zed, and Codex CLI. Clients that are already set up show Configured; use Reconfigure to redo one. If a config file contains comments, click Copy Snippet and paste it in yourself.

When Hillnote writes the config for Claude Desktop, it targets:

PlatformConfig file
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows~/AppData/Roaming/Claude/claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json

Manual configuration

If you'd rather configure the client by hand, the entry launches the bundled server with the Hillnote app itself, running as Node:

{
  "mcpServers": {
    "hillnote-app": {
      "command": "<path-to-hillnote-executable>",
      "args": ["<path-to-hillnote>/mcp-server/index.js"],
      "env": { "ELECTRON_RUN_AS_NODE": "1" }
    }
  }
}

The Local MCP card in Settings → Connections shows this entry with both paths filled in — click Copy to take it from there. (Inside a packaged macOS app, the executable is Hillnote.app/Contents/MacOS/Hillnote and the server lives at Hillnote.app/Contents/Resources/mcp-server/index.js.)

Add this to:

  • Claude Desktop — claude_desktop_config.json (paths above).
  • Cursor — ~/.cursor/mcp.json.
  • VS Code — your user mcp.json, with the entry under "servers" instead of "mcpServers" and "type": "stdio" added.

After saving, fully restart the client.

How access works

No keys, no sign-in. The local server runs as a child process started by your MCP client and reads files directly. There's nothing to sign in to and nothing to paste.

Driving the app asks first. Tools that control the running app (opening documents, switching workspaces, highlighting text) work while Agent interface control is on in Settings → Connections, as it is by default. The first time a client tries, Hillnote asks Allow “…” to control Hillnote? Choose Allow or Don’t allow. Hillnote remembers your choice; change it later with Block or Allow under CONNECTED AGENTS.

The Allow “Claude Code” to control Hillnote? dialog, with Don’t allow and Allow.

It finds your workspaces automatically. On startup the server reads Hillnote's workspace list from the app's config:

PlatformWorkspace list
macOS~/Library/Application Support/Hillnote/workspaces.json
Windows~/AppData/Roaming/Hillnote/workspaces.json
Linux~/.config/Hillnote/workspaces.json

Workspaces you've opened in Hillnote show up by name — no path-juggling required.

It runs with your permissions. The server can touch the same files your user account can. File operations are sandboxed to workspace directories with path-traversal protection, so an assistant can't reach outside your workspaces.

It stays on your machine. No background indexing, no telemetry, no internet requests — its only connection is to the Hillnote app on the same computer, and your content never leaves your computer.

Tool reference

The server exposes more than 70 tools. Read tools never modify anything.

Discover & read

ToolWhat it does
list_workspacesList your local workspaces with document counts
read_registryGet a workspace's full document index — IDs, paths, titles, tags, folders
read_documentRead a document, in full or by line range
search_documentsFuzzy search across filenames, titles, headings, tags, and content, with smart ranking

Documents

ToolWhat it does
add_documentCreate a new document (markdown, slides, or moodboard)
rename_documentRename a document
delete_documentDelete a document (it moves to the workspace trash for 30 days)
insert_contentInsert text at a position, or at the start/end
replace_contentFind and replace text
delete_contentDelete a range of lines or content between patterns
list_trash / restore_from_trashSee what's in the workspace trash, and put a document, row, or database back

Slides

ToolWhat it does
get_slides_story_guideAuthoring guide for writing slide content
get_slides_visual_guideAuthoring guide for styling slides

Moodboards

ToolWhat it does
get_moodboard_guideGuide for building moodboards (.moodboard.md): item types, layout, and connectors
read_moodboardRead every item and connector on a moodboard, with the board's settings
add_moodboard_itemsAdd images, document cards, videos, text and sticky notes, links, colour swatches, frames, shapes, and connectors
update_moodboard_itemsMove, resize, or edit items in place; their connectors stay attached
remove_moodboard_itemsRemove items, along with the connectors attached to them
clear_moodboardEmpty a moodboard to start over (needs confirmation)

To make a board, call add_document with a title ending in .moodboard.md and no content, then fill it with add_moodboard_items. The text-editing tools don't work on moodboards. See Moodboards.

Databases

ToolWhat it does
create_databaseCreate a new database
list_databasesList databases in a workspace
read_databaseRead a database's rows and configuration
delete_databaseDelete a database
add_rows / update_rows / delete_rowsManage database rows
add_column / update_column / delete_columnManage database columns
create_view / list_viewsManage database views
get_board_automation / configure_board_automationSee or set what a board does on its own: the agent each status starts, and auto-moves
schedule_card_move / cancel_scheduled_moveSchedule a card to move to a status, or cancel the move

Sheets

ToolWhat it does
list_sheetsList sheets (CSV-backed datasets) in a workspace
read_sheetRead a sheet's rows, with filtering, sorting, and search
create_sheetCreate a new sheet
add_sheet_rows / update_sheet_rows / delete_sheet_rowsManage sheet rows

Libraries & playbooks

ToolWhat it does
list_librariesList the libraries in a workspace
get_library_mapSee what a library or volume contains
get_library_outlineRead a library's volumes, chapters, and sections
search_librarySearch a library's sections
get_library_sectionRead one section, with a citation to paste
list_playbooks / read_playbookList saved playbooks, or read one with the sources it pins
create_playbook / update_playbookSave or edit a playbook

Recipes

ToolWhat it does
list_recipesList saved prompt recipes
get_recipeRead one recipe
get_recipe_documentsFetch the documents a recipe references
create_recipeSave a new recipe
update_recipeEdit an existing recipe

HTML tools

ToolWhat it does
get_html_tool_guideAuthoring guide for HTML tools
list_html_toolsList the mini-apps in a workspace
get_html_toolRead a mini-app's files
read_html_fileRead one file, in full or by line range
add_html_toolCreate a new mini-app from a set of files
add_tool_to_docEmbed an existing HTML tool into a document
edit_html_toolUpdate a mini-app's metadata or files
write_html_fileCreate or overwrite a file in a mini-app
replace_in_html_fileFind and replace inside a mini-app file
attach_tool_sheetGive a mini-app a sheet to save records in
attach_tool_databaseConnect a database to a mini-app
add_tool_viewShow a mini-app as a Custom view of a database or sheet

App control

These need the Hillnote app running (see Driving the app asks first above).

ToolWhat it does
get_app_stateSee what the app is showing: the open workspace and document
open_document / open_workspaceOpen a document, or switch workspaces
open_database / open_sheet / open_libraryOpen a database, sheet, or library
scroll_to / highlight_textScroll to, or highlight, text in a document
show_slideJump a slide deck to a slide
post_activityPost a status line to the app's agent activity feed
check_previewCheck a page of a Builds project for errors, the way you would see it

Limits

These keep responses fast and predictable:

  • Editing tools (insert, replace, and delete content) work on files up to 10 MB.
  • Tool responses are capped at about 100 KB; a bigger result comes back as a preview, with instructions to fetch a smaller range.

Troubleshooting

The assistant says it has no Hillnote tools, or the connection doesn't appear.
Fully quit and reopen the client (a reload isn't enough — MCP servers are only started on launch). Confirm the config was saved to the right file (see the paths above).

The server won't start.
The entry must launch the Hillnote app's own executable with ELECTRON_RUN_AS_NODE set to 1, and point at its bundled mcp-server/index.js. Compare your config with the Local MCP card, or click Reconfigure for your client.

An empty workspace list.
The server discovers workspaces from workspaces.json written by the Hillnote app. Open a workspace in Hillnote at least once, then ask the assistant to list workspaces again.

Wrong path to the server.
If you configured manually, the bundled paths can change between app versions. Re-copy them from the Local MCP card in Settings → Connections and update your client config.

Tools that open documents say the app isn't running.
App control tools need the Hillnote app open, with Agent interface control on in Settings → Connections. File-based tools keep working without the app.

Changes I made in the app don't show up.
The server reads files from disk. Make sure the file is saved in Hillnote; there's no caching layer to refresh.

Still stuck?
Run hillnote doctor in a terminal. It checks the workspace and the link to the running app, and says what to fix. The command is ready in Hillnote's own terminals; to install it in yours, see Connect your tools.

Privacy & security

  • The server runs entirely on your machine and makes no internet requests; its only connection is to the Hillnote app on the same computer.
  • File operations are validated and sandboxed to your workspace directories — no path traversal outside them.
  • There's no indexing, telemetry, or training on your content.

Questions?

Reach us at [email protected] — or ask your newly connected assistant to draft the email in your workspace. It can do that now.