datanotes-mcp

datanotes-mcp

MCP server for Datanotes: agents read and write your Markdown-notes database through the Datanotes API.

It offers every operation of the Datanotes engine as an MCP tool (list_tables, select_rows, insert_row, undo_migration, …), plus the tools of the apps registered with the engine. Each call is one request to the engine's HTTP API, made with the agent's own token: the engine checks what that token may do and records who did what.

The operation catalogue and the API client come from the datanotes package (datanotes/client), so the tools always match the engine they talk to.

Install

Requires Node.js 20 or newer. Nothing to install: MCP clients start it with npx.

Usage

On your computer (stdio). Point it at a vault. It uses the engine already running there, or starts one (datanotes serve) for as long as the client stays open.

claude mcp add datanotes -- npx -y datanotes-mcp --vault /path/to/vault

{
  "mcpServers": {
    "datanotes": { "command": "npx", "args": ["-y", "datanotes-mcp", "--vault", "/path/to/vault"] }
  }
}

To an engine at an address (stdio):

npx -y datanotes-mcp --url http://127.0.0.1:27150 --token-file ~/.datanotes-token

As a server (Streamable HTTP), for hosted assistants and several clients at once:

npx -y datanotes-mcp serve --engine http://127.0.0.1:27150 --port 27151

Agents connect to http://127.0.0.1:27151/mcp with Authorization: Bearer <token>, where the token is their own Datanotes app token (create one per agent with POST /datanotes/apps/create/). The server keeps no credentials: it passes each agent's token to the engine. To reach it from outside, publish only /mcp through a reverse proxy or a tunnel, over HTTPS.

Full documentation: datanotes.dev/start/connect-agents.

Development

npm install
npm test        # builds, then runs the end-to-end tests against a real engine

License

Apache License 2.0: see LICENSE. Copyright 2026 Davide Fornelli.