hillnote-mcp-server

Rajathbail/hillnote-mcp-server

3.3

If you are the rightful owner of hillnote-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Hillnote MCP Server is the official Model Context Protocol server for Hillnote, enabling AI assistants to interact with document workspaces programmatically.

Tools
5
Resources
0
Prompts
0

Hillnote MCP Server

NPM Version MCP SDK Platform Node

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
  • 🎨 Slide Presentations - Create and edit slide presentations with themes, charts, and templates
  • 🏷️ 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:

  1. Clear npm cache:

    npm cache clean --force

  2. Uninstall and reinstall:

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

  3. 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: "user@example.com",
//     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: "user@example.com",
//     startDate: "2024-01-01",
//     endDate: "2024-01-15",
//     isRecurring: true,
//     recurrenceFrequency: "weekly"  // daily, weekly, monthly, yearly
//   }
// }
// Returns: { success: true, taskName: "...", updatedFields: [...] }

🎨 Slide Presentations

get_slides_guide

Get the comprehensive guide for creating and editing slide presentations in Hillnote.

// No input required
// Returns: Complete guide with syntax, templates, chart types, and best practices

Important: When creating slides with add_document, the title MUST end with .slides.md (e.g., "My Presentation.slides.md"). The .slides.md extension is what makes it a slide presentation.

Example workflow:

// 1. Get the slides guide first
get_slides_guide()

// 2. Create a new slide presentation
add_document({
  workspace: "workspace-name",
  name: "Quarterly Review.slides.md",  // Note: ends with .slides.md
  content: `---
type: slides
theme: minimal
---

# Quarterly Review

Q4 2024 Results

---

# Key Metrics

- Revenue: $1.2M
- Growth: 25%
- Users: 10,000+
`
})

🛠️ 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
│   │   └── slides.js      # Slide presentation guide
│   └── utils/
│       └── helpers.js     # Utility functions
└── README.md

Adding New Tools

  1. Create a new tool file in src/tools/
  2. Export tool definitions and handlers
  3. Import in src/tools/index.js
  4. 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 file

Support

Built with ❤️ by Rajath Bail