Skip to content
MCP server

Notes by Halo

Let AI assistants read, search and edit your local Markdown notes and task checkboxes

Runs locallyStatus and history
Pricing
Free
Platforms
Windows, macOS, CLI
Runs
Locally
Version
1.1.0
Listing updated
2 days ago

About Notes by Halo

Notes by Halo is a free MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.

Notes by Halo keeps notes as plain Markdown files in a folder you choose, and its MCP server works on those files directly. Everything runs locally over stdio. The page states that no Halo cloud copy of your notes is involved and no account is needed for the integration.

Tasks are first-class: list_tasks collects checkboxes across all notes with their completion state, and toggle_task ticks one. Notes can be listed, read, created, updated, deleted and full-text searched, with optional colour filtering. Notes are also exposed as MCP resources, an overview plus one per note.

The server is built into Notes by Halo 1.1.0 or later (free for Windows on the Microsoft Store and for macOS through Homebrew). The app's About screen has a Copy Config button that writes the config pointing at your notes folder. Node.js must be on your PATH. Claude Desktop users can instead install a .mcpb bundle by drag and drop.

Install

Run in a terminal

claude mcp add notes-by-halo-mcp -- npx -y https://github.com/Halo-Software/notes-by-halo-mcp/releases/download/v1.1.0/notes-by-halo-mcp-1.1.0.mcpb

Add to claude_desktop_config.json

{
  "mcpServers": {
    "notes-by-halo-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Halo-Software/notes-by-halo-mcp/releases/download/v1.1.0/notes-by-halo-mcp-1.1.0.mcpb"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "notes-by-halo-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Halo-Software/notes-by-halo-mcp/releases/download/v1.1.0/notes-by-halo-mcp-1.1.0.mcpb"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "notes-by-halo-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Halo-Software/notes-by-halo-mcp/releases/download/v1.1.0/notes-by-halo-mcp-1.1.0.mcpb"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "notes-by-halo-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Halo-Software/notes-by-halo-mcp/releases/download/v1.1.0/notes-by-halo-mcp-1.1.0.mcpb"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "notes-by-halo-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Halo-Software/notes-by-halo-mcp/releases/download/v1.1.0/notes-by-halo-mcp-1.1.0.mcpb"
      ]
    }
  }
}

Tools this server provides (8)

Taken from the project documentation; the running server may differ.

list_notes
Lists all notes with metadata, titles and task summaries.
get_note
Returns a note's full Markdown, metadata and task items by id.
create_note
Creates a note with a Markdown body and optional colour.
update_note
Updates a note's body and/or colour.
delete_note
Deletes a note by id.
search_notes
Full-text AND search with optional colour filter.
list_tasks
Lists all task checkboxes across notes with completion status.
toggle_task
Toggles a specific task's checkbox within a note.

What it does

Local-only access
Runs over stdio on your machine against your own Markdown files.
Note editing
Create, update and delete notes, with optional colour.
Full-text search
AND search across notes, with colour filtering.
Task checkboxes
List all tasks and toggle a specific one.
Resources
Notes are exposed as an overview plus one resource per note.
Copy Config
The app generates the client config for your storage path.

Good for

  • Ask an assistant to summarise a note
  • Find every unchecked task across your notes
  • Create a meeting note from a chat
  • Tick off a completed task without opening the app

Pricing

Free

App is free on the Microsoft Store and via Homebrew

Prices change. Check notes.gethalo.software before you buy.

Notes by Halo FAQ

Is my data sent to a cloud?

The page says everything runs locally and there is no Halo cloud copy of your notes.

What do I need installed?

Notes by Halo 1.1.0 or later and Node.js on your PATH.

Which clients are covered?

Claude Desktop, Cursor and Claude Code, plus other MCP clients.

What if the notes are not found?

Re-copy the config from the About screen and restart your client.

Is Notes by Halo free?

Yes. Notes by Halo is free to use.

How do I add Notes by Halo to Claude Code?

Run this command in your terminal: claude mcp add notes-by-halo-mcp -- npx -y https://github.com/Halo-Software/notes-by-halo-mcp/releases/download/v1.1.0/notes-by-halo-mcp-1.1.0.mcpb

What are the best alternatives to Notes by Halo?

The closest alternatives to Notes by Halo are Codebase Memory, XERJ, Ha MCP, Claude Code Ultimate Guide and Nautilus Compass Memory.

Alternatives to Notes by Halo

  1. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  2. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  3. Ha MCP

    MCP server

    MCP server for managing and automating Home Assistant from AI assistants

    Runs locally
    • 8 tools
    • Open source
    • 7.9K GitHub stars
    • Productivity
  4. MCP server for searching the Claude Code Ultimate Guide from any MCP client

    Runs locally
    • Open source
    • 6.5K GitHub stars
    • AI models and LLM tooling
  5. Local-first long-term memory layer for AI agents, served over MCP

    Not checked yet
    • 5 tools
    • Remote
    • Open source
    • 1.3K GitHub stars
    • Knowledge and memory
  6. Concord MCP

    MCP server

    Local-first MCP server for messaging and shared work-state between coding agents

    Runs locally
    • Freemium
    • 1.3K GitHub stars
    • Developer tools