Notes

What the Notes MCP server does

The Notes MCP server gives an AI agent access to a daily bullet notebook at notes.jpwilliams.dev. It can read the notebook's entities, daily pages, mentions, sub-bullets, co-occurring entities, and open todos. It can also append new bullets to a selected day.

Notes are written into your existing notebook rather than a separate memory store. Agent-created bullets appear in the day view and carry the name assigned to the connection. The mark remains even if you later edit the bullet, so the origin stays visible. Notes can also retain metadata about when and how the agent wrote them, including self-reported vendor, model, and conversation details.

How it works

The service exposes a remote MCP endpoint at https://notes.jpwilliams.dev/api/v1/mcp. An MCP-compatible client discovers the available operations from that URL. During setup, a browser opens so you can sign in to your Notes account, review the access scope, and name the connection. That name is displayed on bullets created through the connection.

The connection can read the whole notebook, including all days, entities, todos, and notes extracted from meeting transcripts. Reads are bounded by the requested notebook structure rather than by a general corpus-search query. Server-side enforcement limits the connection to reading and appending, rather than relying only on tool descriptions.

Setup and configuration

A Notes account is required. For clients that support the Agent Skills format, install the skill with either:

• gh skill install jpwilliams/notes-skill
• npx skills add jpwilliams/notes-skill

The skill is placed in .agents/skills/. Add the MCP endpoint separately in the client. Clients that support remote MCP can use the URL directly without installing a package. The desktop app and website can add the endpoint as a custom connector.

Claude Code has a plugin installation route:

• /plugin marketplace add jpwilliams/notes-skill
• /plugin install notes@notes-skill

No API key, pasted secret, keychain entry, or claude mcp add command is required. You can disconnect a connection from the Machine access page, which stops it from working immediately. Notes already written remain in the notebook.

Tools and capabilities

The Notes MCP server provides four tools:

• list_entities lists projects, people, and topics, with recently mentioned entities first.
• get_entity reads an entity page, including its description, recent mentions and sub-bullets, related entities, and open todos.
• get_day returns a day's page as Markdown along with bullet identifiers.
• append_note adds bullets to a day.

An accompanying agent skill gives guidance on when to consult or update the notebook. The connection itself supplies the tools and server-provided guidance for clients that do not use the plugin.

Limitations and notes

The Notes MCP server is append-only. It cannot edit or delete notebook content, including bullets created by the same agent. To correct a note, add a new bullet; deleting a bullet manually is the correction action described by the service.

Tags must refer to entities that already exist. If an appended note names an unknown entity with a #tag, the complete call is rejected. Entity creation, renaming, and merging are not available through this connection, so projects and other entities must be created manually first.

There is no corpus-wide search, vector index, eviction policy, hooks, or bring-your-own-Postgres option. Agent-written bullets remain visible and marked in the notebook. A display setting can hide them from the day view, but hidden activity still leaves a count, and the marks do not disappear when a bullet is edited.