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	None — the server makes no network requests

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.
Sketch on canvases. Add shapes, text, and arrows to Excalidraw canvases (.canvas.md) for diagrams and visual planning.
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

macOS — Windows support is coming with Hillnote for Windows. (The server itself is cross-platform; packaged support currently targets macOS.)
The Hillnote desktop app installed (it ships the MCP server inside the app).
Node.js 18 or newer on your machine.
An MCP-compatible client — Claude Desktop, Cursor, VS Code with an MCP extension, etc.

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 → MCP.
Hillnote shows the exact configuration for your client, pre-filled with the correct path to the bundled server.
Click Configure Claude Desktop (or copy the snippet for another client). Hillnote writes it to your client's 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.

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 points your client at the bundled server with Node:

{
  "mcpServers": {
    "hillnote": {
      "command": "node",
      "args": ["<path-to-hillnote>/mcp-server/index.js"]
    }
  }
}

The Hillnote app fills in <path-to-hillnote> for you on the Settings → MCP screen — copy it from there. (Inside a packaged macOS app, the server lives at Hillnote.app/Contents/Resources/mcp-server/index.js.)

Add this to:

Claude Desktop — claude_desktop_config.json (paths above).
Cursor — Settings → Features → MCP.
VS Code — your MCP extension's configuration.

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 authorize and nothing to paste.

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 network calls — your content never leaves your computer.

Tool reference

The server exposes tools across eight areas. 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 canvas)
`rename_document`	Rename a document
`delete_document`	Delete a document
`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

Slides & canvas

Tool	What it does
`get_slides_story_guide`	Authoring guide for writing slide content
`get_slides_visual_guide`	Authoring guide for styling slides
`get_canvas_guide`	Layout guide for Excalidraw canvases
`read_canvas`	Read the elements on a canvas
`add_canvas_elements`	Add shapes, text, arrows, and lines to a canvas
`clear_canvas`	Empty a canvas to start over

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

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

Limits

These keep responses fast and predictable:

Individual file reads/writes are capped at 10 MB.
Search returns at most 100 results, ranked by relevance.
Content payloads are capped at roughly 1 MB per operation.

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).

"node: command not found" or the server won't start.
The client needs Node.js 18+ on your PATH. Install Node, then restart the client. If you installed Node via Homebrew, make sure the client can see it (launching the client from a terminal can help on macOS).

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 path can change between app versions. Re-copy the path from Settings → MCP in the app and update your client config.

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.

Privacy & security

The server runs entirely on your machine and makes no network requests.
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.