Connect Notes by Halo to Your AI Assistant (MCP)

Notes by Halo includes a built-in MCP (Model Context Protocol) server, so AI assistants such as Claude Desktop, Cursor, and Claude Code can work directly with your notes: listing and reading them, creating and updating notes, searching the full text, and checking off tasks. Everything runs locally on your own machine over a standard MCP stdio connection. Your notes stay exactly where they have always been, as plain Markdown (.md) files in the folder you chose in Notes by Halo. There is no Halo cloud copy of your notes involved, and no account is needed for the integration itself.

Requirements

• Notes by Halo 1.1.0 or later - free for Windows on the Microsoft Store, and for macOS via Homebrew. The MCP server is built into this version.
• An MCP-compatible AI client, such as Claude Desktop or Cursor (the server also works with Claude Code and other MCP clients).
• Node.js installed on your system: the configuration generated by Notes by Halo starts the server with the node command, so Node.js (for example the LTS version from nodejs.org) must be installed and available on your PATH. No other packages are needed - the server itself ships inside Notes by Halo.

Setup

You do not need to write the configuration by hand. Notes by Halo generates it for you, already pointing at your own notes folder:

1. Open Notes by Halo and go to the About screen.
2. Find the AI & MCP Integration (Model Context Protocol) section.
3. Click Copy Config. This copies a ready-made MCP server configuration that is auto-configured for your current storage path.
4. Paste the configuration into your AI client's MCP config file (see below for each client), save the file, and restart the client.

The generated configuration has this shape (the app fills in the real paths for your installation and your notes folder):

{
  "mcpServers": {
    "halonotes": {
      "command": "node",
      "args": ["<path to halonotes-mcp>", "--data-dir", "<path to your notes data folder>"]
    }
  }
}

Claude Desktop

1. Follow the steps above to copy the configuration from the About screen in Notes by Halo.
2. Open Claude Desktop's MCP configuration file, claude_desktop_config.json, and paste the configuration in. The easiest way to open the right file is Claude Desktop's Settings > Developer > Edit Config, which opens (or creates) the file for you. Its location is %APPDATA%\Claude\claude_desktop_config.json on Windows and ~/Library/Application Support/Claude/claude_desktop_config.json on macOS. If the file already contains other servers, merge the "halonotes" entry into the existing "mcpServers" object.
3. Save the file and restart Claude Desktop. The Notes by Halo tools should then be available to Claude.

Cursor

1. Follow the steps above to copy the configuration from the About screen in Notes by Halo.
2. Open Cursor's global MCP configuration file, mcp.json in the .cursor folder in your home directory (~/.cursor/mcp.json; on Windows, C:\Users\<your name>\.cursor\mcp.json), and paste the configuration in, merging the "halonotes" entry into "mcpServers" if other servers are already defined. Create the file if it does not exist yet.
3. Save the file and restart Cursor (or reload its MCP servers). The Notes by Halo tools should then be available.

Available Tools

Once connected, your AI assistant can use these tools:

The server also exposes your notes as MCP resources (an overview of all notes, plus one resource per note), so clients that support resources can browse them directly.

Troubleshooting

How the server finds your notes

When the server starts, it locates your Notes by Halo data directory in this order:

1. The --data-dir argument, if one is given (the configuration copied from the app already includes this, pointing at your current notes folder).
2. The HALONOTES_DATA_DIR environment variable, if set.
3. Automatic detection: it looks for the app's data folder (named "Notes by Halo") in your system's application data directory, recognising it by the app's config.json or notes-data folder. If you set a custom storage folder inside Notes by Halo, the server follows the folder recorded in the app's configuration.
4. If none of the above is found, it falls back to the default "Notes by Halo" application data folder.

If your notes are not found

• If the client reports that the server failed to start, check that Node.js is installed and that the node command works (for example, run node --version in a terminal). The client starts the server with node, so without Node.js on the PATH the connection cannot start.
• Re-copy the configuration. If you changed the storage folder inside Notes by Halo after copying the configuration, the pasted config may still point at the old folder. Open the About screen, click Copy Config again, and paste the fresh configuration into your client.
• Make sure Notes by Halo has run at least once, so its data folder and configuration exist for the server to detect.
• Restart the AI client after editing its config file; most clients only load MCP servers at startup.
• Check the path manually. Advanced users can start the server with an explicit folder: halonotes-mcp --data-dir <path to your notes data folder>, or set the HALONOTES_DATA_DIR environment variable. Running halonotes-mcp --help prints the available options.

---

日本語の要約

Notes by Halo 1.1.0 には MCP（Model Context Protocol）サーバーが内蔵されており、Claude Desktop や Cursor などの AI アシスタントから、ノートの一覧取得・閲覧・作成・更新・削除、全文検索、タスクの抽出とチェックの切り替えを行えます。設定はアプリの About 画面にある「AI & MCP 連携」セクションの「設定をコピー」ボタンで、ご自身の保存先に合わせた JSON をそのままコピーでき、AI クライアントの設定ファイル（claude_desktop_config.json や .cursor/mcp.json）に貼り付けるだけです。通信はすべてローカル（stdio）で行われ、ノートはこれまで通りお使いのフォルダ内の Markdown ファイルのままです。コピーした設定はサーバーを node コマンドで起動するため、お使いのパソコンに Node.js がインストールされている必要があります。ノートが見つからない場合は、保存先を変更した後に設定をコピーし直すことで解決するケースがほとんどです。