Hillnote MCP Server

Official Model Context Protocol (MCP) server for Hillnote, enabling AI assistants to interact with your document workspaces programmatically.

Platform Support: Currently supports macOS. Windows support coming soon with Hillnote for Windows launch.

Features

📁 Multi-Workspace Support - Manage multiple document workspaces
📝 Document Management - Full CRUD operations for documents
🔍 Smart Search - Fuzzy search with intelligent ranking across titles, tags, and content
✏️ Content Manipulation - Advanced content editing with validation and preview
🎯 AI Recipes - Manage and execute AI prompt recipes
🛠️ HTML Tools - Create interactive HTML-based utilities
📋 Tasklist Management - Create and manage Kanban-style tasklists with full task CRUD operations
🏷️ Metadata Support - Rich document metadata with tags, emojis, and descriptions

Requirements

macOS (Windows support coming soon)
Hillnote Desktop App for macOS
Node.js >= 18.0.0
MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.)

Installation

Option 1: Install from NPM (Recommended)

# Install globally (IMPORTANT: Use -g flag!)
npm install -g @hillnote/mcp-server

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

# If using Homebrew Node.js, the files will be in:
# /opt/homebrew/lib/node_modules/@hillnote/mcp-server/

⚠️ Important: The -g flag is required for global installation. Without it, the package installs locally and won't work with the Claude Desktop configuration.

Option 2: Install from Source

# Clone the repository
git clone https://github.com/HillnoteApp/hillnote-mcp-server.git
cd hillnote-mcp-server

# Install dependencies (NO -g flag needed here)
npm install

Updating to Latest Version

NPM Installation

# Update to the latest version
npm update -g @hillnote/mcp-server

# Or reinstall to force latest version
npm install -g @hillnote/mcp-server@latest

# Check current version
npm list -g @hillnote/mcp-server

# After updating, restart your MCP client (Claude Desktop, Cursor, etc.)

Source Installation

# Navigate to your cloned repository
cd /path/to/hillnote-mcp-server

# Pull latest changes
git pull origin main

# Reinstall dependencies
npm install

# After updating, restart your MCP client

Version Check

To see what version you're currently running:

# For NPM installation
npm list -g @hillnote/mcp-server

# For source installation
cd /path/to/hillnote-mcp-server
cat package.json | grep version

Troubleshooting Updates

If you experience issues after updating:

Clear npm cache:
```
npm cache clean --force
```

Uninstall and reinstall:

npm uninstall -g @hillnote/mcp-server
npm install -g @hillnote/mcp-server

Restart your MCP client completely (not just reload - fully quit and reopen)

Configuration

The MCP server automatically discovers all your Hillnote workspaces from the app's configuration at ~/Library/Application Support/Hillnote/workspaces.json.

Configuration Examples

NPM Installation

If installed via NPM, use your global Node modules path:

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

Find your path with: npm root -g

Source Installation

If cloned from GitHub:

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

Client-Specific Configuration

Claude Desktop

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the configuration above to this file.

Cursor

Location: Settings → Features → MCP

Add the configuration above to the MCP servers section.

VS Code

Install an MCP extension and add the configuration to your settings.json or extension configuration.

Available Tools

📁 Workspace Management

`list_workspaces`

Lists all available workspaces with document counts and metadata.

// No input required
// Returns: Array of workspace objects with path, name, overview, and documentCount

`read_registry`

Get complete workspace overview including all documents, folders, and relationships.

// Input: { workspace: "workspace-name" }
// Returns: Complete registry with documents and folder structure

📄 Document Operations

`read_document`

Read a specific document's content and metadata.

// Input: { workspace: "workspace-name", documentId: "doc-id" }
// Returns: Document content, metadata, and frontmatter

`add_document`

Create a new document with content and metadata.

// Input: {
//   workspace: "workspace-name",
//   name: "Document Name",
//   content: "Document content",
//   emoji: "📄",
//   description: "Brief description",
//   parent: "optional-folder-id"
// }
// Returns: { success: true, documentId: "new-id", fileName: "document-name.md" }

`update_document`

Update an existing document's content or metadata.

// Input: {
//   workspace: "workspace-name",
//   documentId: "doc-id",
//   content: "New content",
//   name: "New Name",
//   emoji: "📝",
//   description: "Updated description"
// }
// Returns: { success: true }

`rename_document`

Rename a document and update its file name.

// Input: { workspace: "workspace-name", documentId: "doc-id", newTitle: "New Title" }
// Returns: { success: true, newFileName: "new-title.md" }

`delete_document`

Delete a document from the workspace.

// Input: { workspace: "workspace-name", documentId: "doc-id" }
// Returns: { success: true }

🔍 Search

`search_documents`

Search documents with fuzzy matching and smart ranking.

// Input: {
//   query: "search term",
//   workspace: "optional-workspace",
//   fuzzy: true,
//   threshold: 0.6,
//   limit: 10
// }
// Returns: Ranked search results with snippets and scores

✏️ Content Manipulation

`insert_content`

Insert content at a specific position with validation.

// Input: {
//   workspace: "workspace-name",
//   documentId: "doc-id",
//   position: "start" | "end" | number | { line: number } | { after: "heading" },
//   text: "Content to insert",
//   validate: true,
//   preview: true
// }
// Returns: { success: true, preview: "...", validation: {...} }

`replace_content`

Replace text in a document with preview and occurrence info.

// Input: {
//   workspace: "workspace-name",
//   documentId: "doc-id",
//   searchText: "text to find",
//   replaceText: "replacement text",
//   all: false,
//   caseSensitive: false,
//   wholeWord: false,
//   useRegex: false
// }
// Returns: { success: true, replacements: 1, preview: "..." }

`delete_content`

Delete content between positions or patterns.

// Input: {
//   workspace: "workspace-name",
//   documentId: "doc-id",
//   startPos: 0 | { line: 5 } | { pattern: "## Section" },
//   endPos: 100 | { line: 10 } | { pattern: "## Next Section" }
// }
// Returns: { success: true, deletedChars: 95, preview: "..." }

`append_to_section`

Append content to a specific markdown section.

// Input: {
//   workspace: "workspace-name",
//   documentId: "doc-id",
//   sectionHeading: "## Notes",
//   content: "Additional notes"
// }
// Returns: { success: true }

🎯 AI Recipe Management

`list_recipes`

List all AI prompt recipes in a workspace.

// Input: { workspacePath: "/path/to/workspace" }
// Returns: Array of recipe objects with metadata

`get_recipe`

Get a specific recipe by ID.

// Input: { workspacePath: "/path/to/workspace", recipeId: "recipe-id" }
// Returns: Complete recipe with prompts and configuration

`add_recipe`

Create a new AI prompt recipe.

// Input: {
//   workspacePath: "/path/to/workspace",
//   name: "Recipe Name",
//   description: "What this recipe does",
//   prompts: [...],
//   config: {...}
// }
// Returns: { success: true, recipeId: "new-id" }

`update_recipe`

Update an existing recipe.

// Input: { workspacePath: "/path/to/workspace", recipeId: "id", updates: {...} }
// Returns: { success: true }

`delete_recipe`

Delete a recipe.

// Input: { workspacePath: "/path/to/workspace", recipeId: "id" }
// Returns: { success: true }

📋 Tasklist Management

`create_tasklist`

Create a new tasklist (Kanban board) in a workspace.

// Input: {
//   workspace: "workspace-name",
//   tasklist: {
//     name: "Project Tasks",
//     columns: [
//       { name: "To Do", color: "blue" },
//       { name: "In Progress", color: "orange" },
//       { name: "Done", isDoneColumn: true, color: "green" }
//     ],
//     viewMode: "projects"  // or "flat"
//   }
// }
// Returns: { success: true, tasklistName: "...", tasklistPath: "documents/...", columns: [...] }

`list_tasklists`

List all tasklists in a workspace.

// Input: { workspace: "workspace-name" }
// Returns: Array of tasklists with task counts, project counts, and columns

`read_tasklist`

Read a complete tasklist structure with all task metadata.

// Input: { workspace: "workspace-name", tasklist: "Project Tasks" }
// Returns: Complete tasklist with columns, projects, tasks, and metadata
// Note: Task content not included - use read_document to read task content

`add_task`

Create a new task in a tasklist.

// Input: {
//   workspace: "workspace-name",
//   tasklist: "Project Tasks",
//   task: {
//     name: "Implement feature X",
//     content: "Task description...",
//     status: "To Do",
//     project: "Backend",  // optional
//     priority: "high",    // low, medium, high
//     assignedTo: "[email protected]",
//     startDate: "2024-01-01",
//     endDate: "2024-01-15",
//     isRecurring: false,
//     emoji: "🔥"
//   }
// }
// Returns: { success: true, taskName: "...", taskPath: "...", status: "..." }

`update_task_status`

Move a task to a different column/status.

// Input: {
//   workspace: "workspace-name",
//   tasklist: "Project Tasks",
//   taskName: "Implement feature X",
//   newStatus: "In Progress"
// }
// Returns: { success: true, taskName: "...", oldStatus: "...", newStatus: "..." }

`update_task_metadata`

Update task properties (priority, assignments, dates, recurring settings).

// Input: {
//   workspace: "workspace-name",
//   tasklist: "Project Tasks",
//   taskName: "Implement feature X",
//   metadata: {
//     priority: "high",
//     assignedTo: "[email protected]",
//     startDate: "2024-01-01",
//     endDate: "2024-01-15",
//     isRecurring: true,
//     recurrenceFrequency: "weekly"  // daily, weekly, monthly, yearly
//   }
// }
// Returns: { success: true, taskName: "...", updatedFields: [...] }

🛠️ HTML Tool Management

`add_html_tool`

Create an interactive HTML tool in the workspace.

// Input: {
//   workspacePath: "/path/to/workspace",
//   toolName: "calculator",
//   description: "Scientific calculator",
//   files: [
//     { name: "index.html", content: "<!DOCTYPE html>..." },
//     { name: "styles.css", content: "body { ... }" },
//     { name: "script.js", content: "// JS code" }
//   ]
// }
// Returns: { success: true, toolPath: "resources/html/calculator", url: "..." }

`list_html_tools`

List all HTML tools in a workspace.

// Input: { workspacePath: "/path/to/workspace" }
// Returns: Array of HTML tools with metadata

`get_html_tool`

Get a specific HTML tool's files.

// Input: { workspacePath: "/path/to/workspace", toolName: "calculator" }
// Returns: Tool info with all file contents

`update_html_tool`

Update an HTML tool's files.

// Input: {
//   workspacePath: "/path/to/workspace",
//   toolName: "calculator",
//   updates: { description: "...", files: [...] }
// }
// Returns: { success: true }

`delete_html_tool`

Delete an HTML tool.

// Input: { workspacePath: "/path/to/workspace", toolName: "calculator" }
// Returns: { success: true }

Workspace Structure

Hillnote workspaces on macOS are typically stored in your Documents folder or custom locations:

~/Documents/YourWorkspace/
├── readme.md                 # Workspace overview
├── documents-registry.json   # Document metadata
├── ai-recipes.json          # AI prompt recipes
├── documents/               # Markdown documents and tasklists
│   ├── document-1.md
│   ├── folder/
│   │   └── document-2.md
│   └── Project Tasks/       # Tasklist (Kanban board)
│       ├── tasklist.json    # Tasklist configuration
│       ├── task-1.md        # Root-level task
│       └── Backend/         # Project folder
│           └── task-2.md    # Task in project
└── resources/               # Assets and tools
    ├── images/             # Image attachments
    └── html/               # HTML tools
        └── tool-name/
            ├── index.html
            └── assets/

Document Format

Documents use Markdown with YAML frontmatter:

---
title: Document Title
tags: [tag1, tag2]
emoji: 📄
description: Brief description
created: 2024-01-01T00:00:00Z
modified: 2024-01-02T00:00:00Z
---

# Document Title

Your content here...

Development

Project Structure

mcp-server/
├── index.js                 # Main server entry point
├── config.json             # Server configuration
├── package.json            # Dependencies
├── src/
│   ├── tools/
│   │   ├── index.js       # Tool aggregator
│   │   ├── workspace.js   # Workspace tools
│   │   ├── document.js    # Document tools
│   │   ├── content.js     # Content manipulation
│   │   ├── search.js      # Search tools
│   │   ├── recipe.js      # Recipe management
│   │   ├── html-tool.js   # HTML tool management
│   │   └── tasklist.js    # Tasklist/Kanban management
│   └── utils/
│       └── helpers.js     # Utility functions
└── README.md

Adding New Tools

Create a new tool file in src/tools/
Export tool definitions and handlers
Import in src/tools/index.js
Tools are automatically available to MCP clients

Running in Development

# Enable watch mode
npm run dev

# Run the server
npm start

Error Handling

All tools use structured error responses:

InvalidParams: Missing or invalid parameters
InternalError: Server-side errors
MethodNotFound: Unknown tool name

Security

File operations are sandboxed to workspace directories
No network requests are made
Path traversal protection included
Input validation on all operations

License

MIT - See LICENSE file

Support

Issues: GitHub Issues
Email: [email protected]
Documentation: Hillnote Docs

Built with ❤️ by Rajath Bail

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
config.json		config.json
index.js		index.js
package.json		package.json

License

Rajathbail/hillnote-mcp-server

Folders and files

Latest commit

History

Repository files navigation

Hillnote MCP Server

Features

Requirements

Installation

Option 1: Install from NPM (Recommended)

Option 2: Install from Source

Updating to Latest Version

NPM Installation

Source Installation

Version Check

Troubleshooting Updates

Configuration

Configuration Examples

NPM Installation

Source Installation

Client-Specific Configuration

Available Tools

📁 Workspace Management

list_workspaces

read_registry

📄 Document Operations

read_document

add_document

update_document

rename_document

delete_document

🔍 Search

search_documents

✏️ Content Manipulation

insert_content

replace_content

delete_content

append_to_section

🎯 AI Recipe Management

list_recipes

get_recipe

add_recipe

update_recipe

delete_recipe

📋 Tasklist Management

create_tasklist

list_tasklists

read_tasklist

add_task

update_task_status

update_task_metadata

🛠️ HTML Tool Management

add_html_tool

list_html_tools

get_html_tool

update_html_tool

delete_html_tool

Workspace Structure

Document Format

Development

Project Structure

Adding New Tools

Running in Development

Error Handling

Security

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`list_workspaces`

`read_registry`

`read_document`

`add_document`

`update_document`

`rename_document`

`delete_document`

`search_documents`

`insert_content`

`replace_content`

`delete_content`

`append_to_section`

`list_recipes`

`get_recipe`

`add_recipe`

`update_recipe`

`delete_recipe`

`create_tasklist`

`list_tasklists`

`read_tasklist`

`add_task`

`update_task_status`

`update_task_metadata`

`add_html_tool`

`list_html_tools`

`get_html_tool`

`update_html_tool`

`delete_html_tool`

Packages