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
| Runs | Locally, on your machine, alongside the Hillnote desktop app |
| Transport | stdio (the client launches the server as a local process) |
| Authentication | None — it operates on files you already own, with your OS permissions |
| What it reaches | Your local Hillnote workspaces, discovered automatically from the app |
| Network | Local 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/mcpthat 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.mdformat 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.
From the Hillnote app (recommended)
- Open Hillnote and go to Settings → Connections, then open the Local MCP card.
- Under CONNECT AN AGENT APP, find your client. Apps found on this computer show Detected and come first.
- 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.
- Click Save Configuration. Hillnote writes it to the config file for you.
- Fully quit and reopen your client — MCP servers are only picked up on a fresh start.
- Start a chat and ask it to "list my Hillnote workspaces" to confirm everything is wired up.

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:
| Platform | Config 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.

It finds your workspaces automatically. On startup the server reads Hillnote's workspace list from the app's config:
| Platform | Workspace 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
| Tool | What it does |
|---|---|
list_workspaces | List your local workspaces with document counts |
read_registry | Get a workspace's full document index — IDs, paths, titles, tags, folders |
read_document | Read a document, in full or by line range |
search_documents | Fuzzy search across filenames, titles, headings, tags, and content, with smart ranking |
Documents
| Tool | What it does |
|---|---|
add_document | Create a new document (markdown, slides, or moodboard) |
rename_document | Rename a document |
delete_document | Delete a document (it moves to the workspace trash for 30 days) |
insert_content | Insert text at a position, or at the start/end |
replace_content | Find and replace text |
delete_content | Delete a range of lines or content between patterns |
list_trash / restore_from_trash | See what's in the workspace trash, and put a document, row, or database back |
Slides
| Tool | What it does |
|---|---|
get_slides_story_guide | Authoring guide for writing slide content |
get_slides_visual_guide | Authoring guide for styling slides |
Moodboards
| Tool | What it does |
|---|---|
get_moodboard_guide | Guide for building moodboards (.moodboard.md): item types, layout, and connectors |
read_moodboard | Read every item and connector on a moodboard, with the board's settings |
add_moodboard_items | Add images, document cards, videos, text and sticky notes, links, colour swatches, frames, shapes, and connectors |
update_moodboard_items | Move, resize, or edit items in place; their connectors stay attached |
remove_moodboard_items | Remove items, along with the connectors attached to them |
clear_moodboard | Empty 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
| Tool | What it does |
|---|---|
create_database | Create a new database |
list_databases | List databases in a workspace |
read_database | Read a database's rows and configuration |
delete_database | Delete a database |
add_rows / update_rows / delete_rows | Manage database rows |
add_column / update_column / delete_column | Manage database columns |
create_view / list_views | Manage database views |
get_board_automation / configure_board_automation | See or set what a board does on its own: the agent each status starts, and auto-moves |
schedule_card_move / cancel_scheduled_move | Schedule a card to move to a status, or cancel the move |
Sheets
| Tool | What it does |
|---|---|
list_sheets | List sheets (CSV-backed datasets) in a workspace |
read_sheet | Read a sheet's rows, with filtering, sorting, and search |
create_sheet | Create a new sheet |
add_sheet_rows / update_sheet_rows / delete_sheet_rows | Manage sheet rows |
Libraries & playbooks
| Tool | What it does |
|---|---|
list_libraries | List the libraries in a workspace |
get_library_map | See what a library or volume contains |
get_library_outline | Read a library's volumes, chapters, and sections |
search_library | Search a library's sections |
get_library_section | Read one section, with a citation to paste |
list_playbooks / read_playbook | List saved playbooks, or read one with the sources it pins |
create_playbook / update_playbook | Save or edit a playbook |
Recipes
| Tool | What it does |
|---|---|
list_recipes | List saved prompt recipes |
get_recipe | Read one recipe |
get_recipe_documents | Fetch the documents a recipe references |
create_recipe | Save a new recipe |
update_recipe | Edit an existing recipe |
HTML tools
| Tool | What it does |
|---|---|
get_html_tool_guide | Authoring guide for HTML tools |
list_html_tools | List the mini-apps in a workspace |
get_html_tool | Read a mini-app's files |
read_html_file | Read one file, in full or by line range |
add_html_tool | Create a new mini-app from a set of files |
add_tool_to_doc | Embed an existing HTML tool into a document |
edit_html_tool | Update a mini-app's metadata or files |
write_html_file | Create or overwrite a file in a mini-app |
replace_in_html_file | Find and replace inside a mini-app file |
attach_tool_sheet | Give a mini-app a sheet to save records in |
attach_tool_database | Connect a database to a mini-app |
add_tool_view | Show 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).
| Tool | What it does |
|---|---|
get_app_state | See what the app is showing: the open workspace and document |
open_document / open_workspace | Open a document, or switch workspaces |
open_database / open_sheet / open_library | Open a database, sheet, or library |
scroll_to / highlight_text | Scroll to, or highlight, text in a document |
show_slide | Jump a slide deck to a slide |
post_activity | Post a status line to the app's agent activity feed |
check_preview | Check 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.