# zennotes-mcp

MCP server that connects AI agents to a self-hosted ZenNotes vault. It wraps the
complete HTTP API of the ZenNotes Go server and exposes it as typed MCP tools,
so agents can read, search, create and organize notes directly.

## Features

65 tools covering the whole vault API:

* vault: info, settings, server-side directory browser
* notes: list, read, write, create, rename, move, duplicate, trash, restore,
  archive, plus `capture`, `append` and `prepend` helpers
* search: full-text search, search capabilities
* tasks: vault-wide aggregation or per note
* folders: create, rename, delete, duplicate
* assets: list, upload, download, rename, move, duplicate, delete, plus the
  deleted-assets trash (list, restore, purge)
* templates and workflows: full CRUD, workflow runs (apply, undo, history)
* comments, Excalidraw drawings, demo tour, session management

## Requirements

* Python 3.10+
* A running ZenNotes server (local `zennotes-server`, Docker image
  `adibhanna/zennotes`, or any remote deployment)

## Install

From source:

```bash
pip install -e .
```

Or directly from GitHub:

```bash
pip install git+https://github.com/PacomeKFP/zennotes-mcp.git
```

This provides the `zennotes-mcp` command.

## Configuration

Everything goes through environment variables. Nothing personal is hardcoded.

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `ZENNOTES_URL` | no | `http://127.0.0.1:7878` | Base URL of the ZenNotes server |
| `ZENNOTES_AUTH_TOKEN` | for protected routes | empty | Bearer token of the server |

```bash
cp .env.example .env  # then fill in your values
export ZENNOTES_URL="http://127.0.0.1:7878"  # or your remote URL
export ZENNOTES_AUTH_TOKEN="your-token-here"
```

Public routes (`health_check`, `get_version`, `get_capabilities`, ...) work
without a token. Everything else returns HTTP 401 until the token is set.

## Run

Stdio mode (for agents):

```bash
zennotes-mcp
```

## Connect an agent

OpenCode v1 (`~/.config/opencode/opencode.jsonc`):

```jsonc
{
  "mcp": {
    "zennotes": {
      "type": "local",
      "command": ["zennotes-mcp"],
      "environment": {
        "ZENNOTES_URL": "http://127.0.0.1:7878",
        "ZENNOTES_AUTH_TOKEN": "your-token-here"
      },
      "enabled": true
    }
  }
}
```

OpenCode v2 moves the same block under `mcp.servers` (see
`opencode.json.example`). The same stdio command also works in Claude Code,
Claude Desktop and Codex. Restart the agent after editing the config, as MCP
servers connect at startup.

## Examples

Once connected, just ask:

* "with zennotes, list my notes"
* "find my notes about backups and summarize them in a new note"
* "capture this in my quick notes: ..."

## Development

```bash
pip install -e .
python tests/test_smoke.py  # public endpoints, no token needed
```

`ZENNOTES_URL` can point at a remote server for the smoke test:

```bash
ZENNOTES_URL="https://my-server.example.com" python tests/test_smoke.py
```

## Security

* The auth token only ever lives in environment variables or your local agent
  config. Never commit it: `.env` is git-ignored.
* Prefer read-only prompts for shared agents, and keep `delete`, `empty_trash`
  and `session_rotate_token` for supervised use.

## Roadmap

Progressive updates following ZenNotes releases: tags endpoint if re-exposed,
real-time watch events, batch operations.