MCP servers

Znote speaks MCP (Model Context Protocol) — the open standard that connects AI models to real tools. Plug a server into your vault and any AI code block can query your database, list your GitHub PRs, drive a browser or read your filesystem, with the answer saved in the note.

Servers run as local processes: Znote starts them, talks to them over stdio, and stops them when the window closes. Your tokens and credentials stay in your vault's config and go directly to the services you configured.

Declare servers — .znote/mcp.json

Servers are declared per vault in .znote/mcp.json, using the same format as Claude Desktop. Every MCP server README on the internet shows a config snippet — it pastes into Znote as-is.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allow"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  }
}

Each server accepts:

Key	Purpose
command	Executable to launch (npx, uvx, docker, an absolute path…)
args	Command arguments
env	Extra environment variables (API tokens…)
cwd	Working directory (optional)
disabled	true to keep the entry without starting it (optional)

The "＋ mcp.json" button

When a note contains a json block with an mcpServers config — like the one above — Znote shows a ＋ mcp.json button on it. One click merges the servers into your vault's config. An MCP setup guide written as a note is also its own installer.

Settings → MCP

Settings → MCP lists every declared server. The ▶ Test button connects and lists the tools the server exposes; Open mcp.json creates or opens the config file (with a working filesystem example on first use); Reload re-reads it after manual edits.

If a connection fails, the error is meant to be actionable: a missing runtime shows the exact install command for your OS, a crashed server shows its last stderr lines.

Runtime requirements

Most servers are launched with npx (Node.js) or uvx (Python, via uv):

Runtime	macOS	Windows	Linux
Node.js (npx)	brew install node	winget install OpenJS.NodeJS.LTS	apt install nodejs npm
uv (uvx)	brew install uv	winget install astral-sh.uv	curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

After installing a runtime on Windows, restart Znote — the app's environment is frozen at launch. On macOS and Linux the new command is picked up automatically.

Use tools in a note

Reference a server with the tools= parameter of an ```ai block:

```ai tools=github
Open PRs and yesterday's commits on acme/webapp — draft my standup brief.
```

The model calls the server's tools — as many as it needs, in a loop — and the answer lands below the block, saved in the note as rendered markdown.

Syntax	Effect
tools=github	Expose all the server's tools
tools=playwright.browser_navigate	Expose a single tool
tools=github,postgres	Combine several servers
tools=github,myFunction	Mix servers with your own JS functions

Autocompletion on tools= suggests your declared servers, and their individual tools once a server has been connected.

Remote servers

Remote-only servers (Linear, Notion, Sentry…) work through the standard mcp-remote bridge, which handles the OAuth flow in your browser:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
    }
  }
}

Troubleshooting

• command 'npx' not found / command 'uvx' not found — the runtime is missing: use the install command from the error (or the table above). On Windows, restart Znote after installing.

• A tool fails and the AI paraphrases the error — ask for the raw message; this works with any server:

  ```ai tools=playwright
  Navigate to https://example.com and if it fails, show me the EXACT
  raw error message from the tool, verbatim, without rephrasing.
  ```

• Config errors (invalid JSON, missing command) are shown at the top of Settings → MCP — the file is never overwritten silently.

Ready-to-run examples

22 example notes — one per server: Filesystem, Postgres, SQLite, GitHub, Playwright, Linear, Jira, Notion, Slack, Google Workspace, Stripe, Sentry, Grafana, Zapier and more. Each has the exact config, the prerequisites, and prompts you can run as-is.

First step

The filesystem server is the best starting point: no token, no account — and your AI can suddenly read that log file you were about to copy-paste.