Hillnote MCP Server for Document Workspaces

Overview

The Hillnote MCP Server implements the Model Context Protocol (MCP) for Hillnote document workspaces, allowing AI assistants and MCP-compatible clients to programmatically access, query, and modify notes, databases, slides, and canvases stored in Hillnote. By running this lightweight Node.js server locally, tools such as Claude Desktop, Cursor, or MCP-enabled VS Code extensions can discover your Hillnote workspaces and perform structured operations (read, search, edit, and more) without manual file handling.

This server is useful for building AI-driven workflows: you can ask an assistant to search across multiple workspaces, generate slide decks from a document, run bulk edits, or surface kanban/task data to an external planner. The MCP server exposes a curated set of endpoints that map common user interactions into safe, validated operations on Hillnote content.

Features

• Multi-workspace discovery and listing
• Read/write CRUD for documents with metadata (tags, emojis, descriptions)
• Fuzzy search across titles, tags, and content with ranking
• Content editing with validation and preview workflows
• AI recipe management and execution (prompt templates / workflows)
• HTML tools for interactive, embeddable utilities
• Structured databases: rows, columns, views, and kanban boards
• Two-phase slide generation (story → visual design)
• Excalidraw-compatible canvas creation and editing
• Cross-platform support: macOS, Windows, Linux

Requirements

The MCP server discovers Hillnote workspaces from the app configuration (see locations below).

Installation / Configuration

Install from NPM (recommended, global install required):

# Install globally
npm install -g @hillnote/mcp-server

# Verify installation
npm list -g @hillnote/mcp-server

Install from source (if you prefer to run the repository directly):

git clone https://github.com/Rajathbail/hillnote-mcp-server.git
cd hillnote-mcp-server
npm install
# Start with node index.js (or use your own process manager)

Common workspace discovery locations:

• macOS: ~/Library/Application Support/Hillnote/workspaces.json
• Windows: %APPDATA%/Hillnote/workspaces.json
• Linux: ~/.config/Hillnote/workspaces.json

MCP client configuration examples

• NPM/global install (command uses the installed binary):

{
  "mcpServers": {
    "hillnote": {
      "command": "hillnote-mcp"
    }
  }
}

• Running from source (call node with index.js):

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

After installation or update, restart your MCP client so it re-discovers servers.

Available Tools

The MCP server exposes tool-like endpoints (method names shown as examples). Input/outputs are JSON structures appropriate for MCP calls.

• Workspace management
  • list_workspaces: returns workspace list with name, path, document counts
  • read_registry: full workspace index (folders, document references)
• Document operations
  • read_document: fetch content + metadata
  • add_document: create a new document
  • edit_document: apply edits with preview/validation
  • delete_document: remove a document
• Search
  • search_documents: fuzzy search across title, tags, content with scoring
• AI Recipes & HTML Tools
  • list_recipes, run_recipe, create_html_tool: manage and run prompt templates and web widgets
• Structured collections
  • create_database, list_rows, update_row, create_view, kanban_move: work with Hillnote databases and views
• Slides & Canvas
  • generate_slides: two-phase generation (storyboard → visual slides)
  • read_canvas / write_canvas: read or edit Excalidraw-compatible canvases
• Metadata
  • update_metadata: add tags, emojis, descriptions, custom properties

Example call payload (pseudo):

// read_document
{
  "workspace": "research",
  "documentId": "abc123"
}

Responses include content (Markdown/HTML), frontmatter, and metadata.

Use Cases

• Research assistant: Run search_documents to fetch relevant notes, then use run_recipe to summarize findings into a short brief or bibliography.
• Bulk updates: Use read_registry to list documents and edit_document in a loop to update frontmatter or add standardized tags.
• Slide generation: Feed a long-form document to generate_slides to produce a storyboard, then iterate visually to create final slides.
• Task sync: Export Hillnote kanban or database rows via list_rows and sync with external task managers or retrospectives.
• Interactive utilities: Create HTML tools for calculators, code runners, or data visualizers embedded in notes and execute them via create_html_tool.

Tips & Troubleshooting

• Always install the package globally when using the NPM distribution so MCP clients can call the command directly.
• If a client doesn’t discover the server, restart the MCP client and verify the JSON configuration path is correct.
• To update, use npm update -g @hillnote/mcp-server or pull the repo and npm install for source installs.
• If issues occur after upgrade: clear npm cache, reinstall, and restart both the MCP client and the Hillnote app.

Repository and source code: https://github.com/Rajathbail/hillnote-mcp-server