WhyNote

What the WhyNote MCP server does

WhyNote MCP server exposes read-only access to the notes in one WhyNote account. It gives an MCP-compatible AI client four ways to retrieve information: search note lines by a case-insensitive substring, list todo items, read a complete note for a date, and inspect existing note days around an anchor date.

The server does not provide note creation, editing, deletion, or other write operations. It is suited to assistants that need to answer questions from personal notes, find unfinished tasks, or review entries from a particular period without receiving account credentials.

How it works

The WhyNote MCP server runs as a local Node.js process and communicates with the MCP client using the client’s configured server transport. The supplied NOTE_URL identifies the WhyNote service, while NOTE_TOKEN authenticates requests as a read-only bearer credential.

search looks for a case-insensitive string within note lines. todos returns either incomplete tasks or the full todo set, depending on the request. read_day retrieves the complete note for one date and includes its etag. recent_days returns existing note days near a supplied anchor date, which can help an agent discover available entries before reading one.

Requests are sent to the configured WhyNote URL. The token is read from the process environment and is used only as a bearer credential for that configured service. The server does not receive the account password.

Setup and configuration

Create a read-only token in WhyNote settings before configuring the client. Add an MCP server entry that runs:

npx -y why-note-mcp

Set these environment variables:

• NOTE_URL: the URL of the WhyNote service
• NOTE_TOKEN: the account’s read-only token

Node.js 18 or newer is required. The README documents setup examples for Claude Code and Codex CLI, as well as a generic JSON configuration format. Avoid placing the token directly in shell commands when possible, because command arguments may remain in shell history; edit the client configuration instead.

Changing the WhyNote account password revokes read-only tokens. If a token expires or is revoked, generate another one in WhyNote settings and update the client configuration.

Tools and capabilities

• search: finds note lines containing a case-insensitive substring.
• todos: lists incomplete todo items or all todo items.
• read_day: reads the full note for a specified date and returns its etag.
• recent_days: reads existing note days near an anchor date.

Together, these tools support both targeted retrieval and date-based exploration. An agent can search for a phrase, identify unfinished work, inspect a known day, or locate nearby days before requesting their full contents.

Limitations and notes

The WhyNote MCP server is read-only. It cannot update notes or todos, and it cannot perform account actions. It works with one configured WhyNote account and requires a valid read-only token plus the correct service URL.

The project describes itself as zero-dependency and includes tests that use a local fake HTTP service, so development tests do not require a WhyNote account, network access, or third-party services. These testing details do not change the runtime requirement for Node.js 18 or newer and valid account configuration.