# Notes by Halo

> Notes by Halo is a free MCP server for knowledge and memory. Let AI assistants read, search and edit your local Markdown notes and task checkboxes. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** Windows, macOS, CLI
- **Website:** https://notes.gethalo.software/mcp.html
- **MCP Registry name:** io.github.Halo-Software/notes-by-halo-mcp
- **Categories:** knowledge and memory, productivity
- **Listing updated:** 2026-11-14

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

```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"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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"
      ]
    }
  }
}
```

## Tools

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

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

- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.

---
Source: https://ai-powered.com/mcp/notes-by-halo
