Skip to content
Back to search

affine-mcp-server

Model Context Protocol server for AFFiNE. Connect AI assistants to AFFiNE workspaces, documents, databases, and collaboration APIs over stdio or HTTP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/DAWNCR0W/affine-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/DAWNCR0W/affine-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dawncr0w--affine-mcp-server/badge.svg)](/listings/dawncr0w--affine-mcp-server)

HTML

<a href="/listings/dawncr0w--affine-mcp-server"><img src="/api/listings/dawncr0w--affine-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the CLI

npm i -g affine-mcp-server
affine-mcp --version

You can also run the package ad hoc:

npx -y -p affine-mcp-server affine-mcp -- --version

2. Or run the server in Docker

docker run -d \
  -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e AFFINE_BASE_URL=https://your-affine-instance.com \
  -e AFFINE_EMAIL=you@example.com \
  -e AFFINE_PASSWORD=your-password \
  -e AFFINE_MCP_AUTH_MODE=bearer \
  -e AFFINE_MCP_HTTP_TOKEN=your-strong-secret \
  ghcr.io/dawncr0w/affine-mcp-server:3.8.5

Then point your client at:

{
  "mcpServers": {
    "affine": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-strong-secret"
      }
    }
  }
}

For Docker, health checks, and remote deployment details, see [docs/configuration-and-deployment.md#docker](docs/configuration-and-deployment.md#docker).

HTTP deployments have two environment-only session limits:

| Variable | Default | Purpose | | --- | --- | --- | | `AFFINE_MCP_HTTP_MAX_SESSIONS` | `32` | Combined Streamable HTTP and legacy SSE session capacity, including sessions being initialized | | `AFFINE_MCP_HTTP_SESSION_IDLE_TIMEOUT_MS` | `1800000` (30 minutes) | Idle time before an inactive session is closed |

Short-lived Streamable HTTP clients, including cron jobs, should send `DELETE /mcp` with their `Mcp-Session-Id` and authentication headers when finished. Exiting the client process alone does not terminate its server-side session. A long idle timeout can let abandoned sessions fill the limit and cause `503` / `-32002` errors. Close unused sessions and choose an appropriate idle timeout before raising the cap. See [session capacity troubleshooting](docs/configuration-and-deployment.md#runtime-limits-and-shutdown).

3. Save credentials with interactive login

affine-mcp login

This stores credentials in `$XDG_CONFIG_HOME/affine-mcp/config` when `XDG_CONFIG_HOME` is set, otherwise in `~/.config/affine-mcp/config`, with mode `600`.

The login flow reuses the configured or saved AFFiNE URL when you press Enter at the URL prompt. After authentication, workspace discovery displays the workspace name first and falls back to `Workspace name unavailable` when profile metadata has no name; the full ID remains visible. An invalid numeric selection is rejected and prompted again. Enter `q` or send end-of-file to cancel without writing a new config. A failed discovery request is reported as a failure; it is not treated as a completed login.

- For AFFiNE Cloud, paste the Cookie request header from a signed-in browser session - For self-hosted AFFiNE, use email/password (recommended) or a signed-in session cookie - `AFFINE_API_TOKEN` remains available only for deployments that still accept a compatible GraphQL bearer token

The prompt defaults to `AFFINE_BASE_URL` from the environment or the saved config file, so pressing Enter keeps an already-configured self-hosted URL instead of switching back to AFFiNE Cloud.

For a self-hosted instance reached over plain HTTP on a trusted private network, `AFFINE_ALLOW_INSECURE_HTTP=true` must be set for the login run as well as for the server. The opt-in is read from the environment first and then from the saved config file.

To avoid re-running login when a session expires, persist the account credentials instead of the session cookie:

affine-mcp login --save-credentials

With the email/password method, this stores `AFFINE_EMAIL` and `AFFINE_PASSWORD` so the server signs in on its own and renews the session before it expires. The password is written to the mode-`600` config file, so use a dedicated least-privilege AFFiNE account. Without this flag the CLI keeps storing only the session credential, which never renews by itself.

For scripted session-cookie setup, keep the cookie out of process arguments:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 402 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # AFFiNE MCP Server
  2. A Model Context Protocol (MCP) server for AFFiNE. It exposes AFFiNE workspaces and documents to AI assistants over stdio (default) or HTTP (`/mcp`) and supports both AFFiNE Cloud and self-hosted deployments.
  3. [![Version](https://img.shields.io/badge/version-3.14.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
  4. [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.32.2-green)](https://github.com/modelcontextprotocol/typescript-sdk)
  5. [![CI](https://github.com/dawncr0w/affine-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/dawncr0w/affine-mcp-server/actions/workflows/ci.yml)
  6. [![License](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
  7. <a href="https://glama.ai/mcp/servers/@DAWNCR0W/affine-mcp-server">
  8. <img width="380" height="200" src="https://glama.ai/mcp/servers/@DAWNCR0W/affine-mcp-server/badge" alt="AFFiNE Server MCP server" />
  9. </a>
  10. ## Table of Contents
  11. - [Overview](#overview)
  12. - [Choose Your Path](#choose-your-path)
  13. - [Quick Start](#quick-start)
  14. - [Compatibility Matrix](#compatibility-matrix)
  15. - [Tool Surface](#tool-surface)
  16. - [Documentation Map](#documentation-map)
  17. - [Verify Your Setup](#verify-your-setup)
  18. - [Security and Scope](#security-and-scope)
  19. - [Development](#development)
  20. - [Release Notes](#release-notes)
  21. - [License](#license)
  22. - [Support](#support)
  23. ## Overview
  24. AFFiNE MCP Server is designed for three common scenarios:
  25. - Run a local stdio MCP server for Claude Code, Codex CLI, Cursor, or Claude Desktop
  26. - Expose a remote HTTP MCP endpoint for hosted or browser-connected clients
  27. - Automate AFFiNE workspace, document, database, organization, and comment workflows through a stable MCP tool surface
  28. Highlights:
  29. - Supports AFFiNE Cloud and self-hosted AFFiNE instances
  30. - Supports stdio and HTTP transports
  31. - Coordinates concurrent writes per workspace through one shared MCP server. Pass a returned document revision string as `expectedRevision` to reject stale edits. Resaving a title that already matches keeps its revision.
  32. - Supports session-cookie and email/password authentication, plus compatible bearer tokens for older deployments
  33. - Exposes 114 canonical MCP tools backed by AFFiNE GraphQL, WebSocket, and REST APIs
  34. - Reads native database `created-by` (user ID) and `created-time` (timestamp) columns from row metadata; missing or invalid metadata returns `null` without backfilling it
  35. - Creates and updates code blocks with optional native preview state, with language and preview readback
  36. - Places, resizes, and connects images on edgeless canvases, with blob identifiers and geometry in readback
  37. - Appends canvas frames in creation-order presentation sequence while preserving their native background layering
  38. - Sets and clears native AFFiNE Journal dates with `set_doc_journal`
  39. - Includes semantic page composition, native template instantiation, database intent composition, capability and fidelity reporting, and workspace blueprint helpers
  40. - Includes Docker images, health probes, and end-to-end test coverage
  41. Scope boundaries:
  42. - This server can access only server-backed AFFiNE workspaces
  43. - Browser-local workspaces stored only in local storage are not available through AFFiNE server APIs
  44. - After a content write, transient workspace timestamp failures are retried up to three times with backoff. If metadata still cannot be confirmed, inspect the saved document before any repair; do not repeat the content edit. See [document mutation recovery](docs/tool-reference.md#content-editing).
  45. - AFFiNE 0.27+ removed the legacy personal-access-token GraphQL API; this server no longer exposes token-management tools
  46. - AFFiNE Cloud requires browser-session authentication for this external GraphQL integration; programmatic email/password sign-in is blocked by Cloudflare
  47. - `delete_doc` removes workspace page metadata and requests content deletion. Some AFFiNE servers retain content despite acknowledging the request; the tool returns a partial result with a warning unless content absence is verified. Use `trash_doc` for recoverable cleanup.
  48. > v3.14.0 adds lightweight document revision lookups, targeted block reads, and batch edits. Successful content writes return revisions that clients can reuse to check subsequent edits.
  49. ## Choose Your Path
  50. | Goal | Start here |
  51. | --- | --- |
  52. | Set up a local stdio server with the least friction | [docs/getting-started.md](docs/getting-started.md) |
  53. | Run the server in Docker or another OCI runtime | [docs/getting-started.md#path-c-run-from-the-docker-image](docs/getting-started.md#path-c-run-from-the-docker-image) |
  54. | Configure Claude Code, Claude Desktop, Codex CLI, or Cursor | [docs/client-setup.md](docs/client-setup.md) |
  55. | Let multiple agents write through one coordinated server | [Concurrent writes](docs/configuration-and-deployment.md#concurrent-writes) |
  56. | Run the server remotely over HTTP or behind OAuth | [docs/configuration-and-deployment.md](docs/configuration-and-deployment.md) |
  57. | Lock down tool exposure for least-privilege deployments | [docs/configuration-and-deployment.md#least-privilege-tool-exposure](docs/configuration-and-deployment.md#least-privilege-tool-exposure) |
  58. | Learn common AFFiNE workflows and tool sequences | [docs/workflow-recipes.md](docs/workflow-recipes.md) |
  59. | Browse the tool catalog by domain | [docs/tool-reference.md](docs/tool-reference.md) |
  60. ## Quick Start
  61. ### 1. Install the CLI
  62. ```bash
  63. npm i -g affine-mcp-server
  64. affine-mcp --version
  65. ```
  66. You can also run the package ad hoc:
  67. ```bash
  68. npx -y -p affine-mcp-server affine-mcp -- --version
  69. ```
  70. ### 2. Or run the server in Docker
  71. ```bash
  72. docker run -d \
  73. -p 3000:3000 \
  74. -e MCP_TRANSPORT=http \
  75. -e AFFINE_BASE_URL=https://your-affine-instance.com \
  76. -e AFFINE_EMAIL=you@example.com \
  77. -e AFFINE_PASSWORD=your-password \
  78. -e AFFINE_MCP_AUTH_MODE=bearer \
  79. -e AFFINE_MCP_HTTP_TOKEN=your-strong-secret \
  80. ghcr.io/dawncr0w/affine-mcp-server:3.14.0
  81. ```
  82. Then point your client at:
  83. ```json
  84. {
  85. "mcpServers": {
  86. "affine": {
  87. "type": "http",
  88. "url": "http://localhost:3000/mcp",
  89. "headers": {
  90. "Authorization": "Bearer your-strong-secret"
  91. }
  92. }
  93. }
  94. }
  95. ```
  96. For Docker, health checks, and remote deployment details, see [docs/configuration-and-deployment.md#docker](docs/configuration-and-deployment.md#docker).
  97. HTTP deployments have two environment-only session limits:
  98. | Variable | Default | Purpose |
  99. | --- | --- | --- |
  100. | `AFFINE_MCP_HTTP_MAX_SESSIONS` | `32` | Combined Streamable HTTP and legacy SSE session capacity, including sessions being initialized |
  101. | `AFFINE_MCP_HTTP_SESSION_IDLE_TIMEOUT_MS` | `1800000` (30 minutes) | Idle time before an inactive session is closed |
  102. Short-lived Streamable HTTP clients, including cron jobs, should send `DELETE /mcp`
  103. with their `Mcp-Session-Id` and authentication headers when finished. Exiting the
  104. client process alone does not terminate its server-side session. A long idle
  105. timeout can let abandoned sessions fill the limit and cause `503` / `-32002`
  106. errors. Close unused sessions and choose an appropriate idle timeout before
  107. raising the cap. See [session capacity troubleshooting](docs/configuration-and-deployment.md#runtime-limits-and-shutdown).
  108. ### 3. Save credentials with interactive login
  109. ```bash
  110. affine-mcp login
  111. ```
  112. This stores credentials in `$XDG_CONFIG_HOME/affine-mcp/config` when `XDG_CONFIG_HOME` is set, otherwise in `~/.config/affine-mcp/config`, with mode `600`.
  113. The login flow reuses the configured or saved AFFiNE URL when you press Enter at
  114. the URL prompt. After authentication, workspace discovery displays the workspace
  115. name first and falls back to `Workspace name unavailable` when profile metadata
  116. has no name; the full ID remains visible. An invalid numeric selection is rejected
  117. and prompted again. Enter `q` or send end-of-file to cancel without writing a new
  118. config. A failed discovery request is reported as a failure; it is not treated as
  119. a completed login.
  120. - For AFFiNE Cloud, paste the Cookie request header from a signed-in browser session
  121. - For self-hosted AFFiNE, use email/password (recommended) or a signed-in session cookie
  122. - `AFFINE_API_TOKEN` remains available only for deployments that still accept a compatible GraphQL bearer token
  123. The prompt defaults to `AFFINE_BASE_URL` from the environment or the saved config file, so pressing Enter keeps an already-configured self-hosted URL instead of switching back to AFFiNE Cloud.
  124. For a self-hosted instance reached over plain HTTP on a trusted private network, `AFFINE_ALLOW_INSECURE_HTTP=true` must be set for the login run as well as for the server. The opt-in is read from the environment first and then from the saved config file.
  125. To avoid re-running login when a session expires, persist the account credentials instead of the session cookie:
  126. ```bash
  127. affine-mcp login --save-credentials
  128. ```
  129. With the email/password method, this stores `AFFINE_EMAIL` and `AFFINE_PASSWORD` so the server signs in on its own and renews the session before it expires. The password is written to the mode-`600` config file, so use a dedicated least-privilege AFFiNE account. Without this flag the CLI keeps storing only the session credential, which never renews by itself.
  130. For scripted session-cookie setup, keep the cookie out of process arguments:
  131. ```bash
  132. affine-mcp login --url https://app.affine.pro --cookie-stdin --workspace-id your-workspace-id --force
  133. ```
  134. Paste the cookie at the hidden prompt, or pipe it from a trusted secret source. The CLI verifies `--workspace-id` against the authenticated account before saving it. Piped input requires `--force` when existing credentials would be replaced.
  135. After login, inspect and switch the saved default workspace without signing in
  136. again:
  137. ```bash
  138. affine-mcp workspaces
  139. affine-mcp workspaces --json
  140. affine-mcp workspace <workspace-id>
  141. ```
  142. `workspaces` lists names first and marks the current default. `workspace` validates
  143. the requested ID with the active credentials and changes only the local default
  144. (`AFFINE_WORKSPACE_ID`); it does not grant access to a workspace or change the
  145. authenticated account. With no ID, it uses the same validated selection flow.
  146. ### 4. Register the server with your client
  147. Claude Code project config:
  148. ```json
  149. {
  150. "mcpServers": {
  151. "affine": {
  152. "command": "affine-mcp"
  153. }
  154. }
  155. }
  156. ```
  157. Codex CLI:
  158. ```bash
  159. codex mcp add affine -- affine-mcp
  160. ```
  161. More client-specific setup is in [docs/client-setup.md](docs/client-setup.md).
  162. ### 5. Verify the connection
  163. ```bash
  164. affine-mcp status
  165. affine-mcp doctor
  166. affine-mcp snippet codex
  167. ```
  168. The recommended Codex form is a command-only registration line that keeps using
  169. the current saved login. `snippet claude` and `snippet cursor` print JSON
  170. configuration instead. Apply the generated snippet, then restart or reconnect
  171. the MCP client so it starts a fresh server process.
  172. For an explicit environment snapshot, add `--env` to any snippet command. It
  173. copies the currently resolved URL, authentication, headers, workspace, and
  174. relevant OAuth settings; client environment variables win over saved config at
  175. runtime. Remove or regenerate copied credentials when they expire instead of
  176. expecting a saved login to override them.
  177. If you want to expose the server remotely over HTTP instead of stdio, start with [docs/configuration-and-deployment.md](docs/configuration-and-deployment.md).
  178. If an HTTP server already runs on the same host as your stdio client, use the
  179. private [stdio HTTP bridge](docs/configuration-and-deployment.md#private-stdio-bridge-for-a-local-http-listener)
  180. instead of starting another full server process.
  181. ## Compatibility Matrix
  182. Node.js 20.18.1 is the minimum supported runtime. CI validates the Node.js 20, 22, 24, and 26 release lines.
  183. | Target | Transport | Recommended auth | Recommended path |
  184. | --- | --- | --- | --- |
  185. | Claude Code | stdio | Saved config | [docs/client-setup.md#claude-code](docs/client-setup.md#claude-code) |
  186. | Claude Desktop | stdio | Saved config or session cookie | [docs/client-setup.md#claude-desktop](docs/client-setup.md#claude-desktop) |
  187. | Codex CLI | stdio | Saved config or self-hosted email/password | [docs/client-setup.md#codex-cli](docs/client-setup.md#codex-cli) |
  188. | Cursor | stdio | Saved config or session cookie | [docs/client-setup.md#cursor](docs/client-setup.md#cursor) |
  189. | Containerized remote deployment | HTTP | Bearer token or OAuth | [docs/getting-started.md#path-c-run-from-the-docker-image](docs/getting-started.md#path-c-run-from-the-docker-image) |
  190. | Remote MCP clients | HTTP | Bearer token or OAuth | [docs/configuration-and-deployment.md#http-mode](docs/configuration-and-deployment.md#http-mode) |
  191. | AFFiNE Cloud | stdio or HTTP | Signed-in browser session cookie | [docs/configuration-and-deployment.md#auth-strategy-matrix](docs/configuration-and-deployment.md#auth-strategy-matrix) |
  192. | Self-hosted AFFiNE | stdio or HTTP | Email/password or session cookie | [docs/configuration-and-deployment.md#auth-strategy-matrix](docs/configuration-and-deployment.md#auth-strategy-matrix) |
  193. ## Tool Surface
  194. `tool-manifest.json` is the source of truth for canonical tool names. The MCP server exposes those tools through `tools/list` and `tools/call`; tool definitions returned by `tools/list` include MCP annotations that mark read-only, destructive, idempotent, and external-world behavior for client-side tool selection.
  195. Every canonical tool also declares an MCP `outputSchema` for its `structuredContent`. Object results retain their existing top-level fields, while array and scalar results use stable `{ items }`, `{ text }`, or `{ value }` envelopes. The existing text `content` remains unchanged for compatibility with clients that do not consume structured results.
  196. `get_capabilities` exposes the full implemented list in
  197. `server.supportedTools` and the currently enabled surface in
  198. `server.effective.profile` and `server.effective.enabledTools`, after profiles,
  199. disabled groups or tools, and auth-mode policy. Inspect `tools/list` when you
  200. need the final set of callable tools.
  201. Advertised input and output schemas omit the SDK-generated draft-07 `$schema` marker. Schema interpretation follows the client context, allowing clients that reject an explicit draft-07 declaration to consume the tool surface.
  202. Domains:
  203. - Workspace: create, inspect, update, delete, and traverse workspaces
  204. - Organization: collections, collection-rule sync, workspace blueprints, and experimental organize or folder helpers
  205. - Documents: search, read, create, publish, move, tag, custom properties, import/export, semantic composition, template inspection and native instantiation, capability and fidelity reporting, and block-level mutation
  206. - Databases: create columns, add rows, update rows, inspect schema, add table/kanban views, and compose database structures from intent
  207. - Comments: list, create, update, delete, and resolve
  208. - History: version history listing
  209. - Users and authentication: current user, sign-in, and profile/settings
  210. - Notifications: list and mark notifications as read
  211. - Blob storage: upload, delete, and cleanup blobs
  212. For new document content, use `create_doc` for an optional single plain-text
  213. paragraph and `create_doc_from_markdown` for native headings, lists, links,
  214. code blocks, and `$$...$$`/`$...$` math equations. Both tools accept `folderId` for immediate organize-folder placement.
  215. New pages record the authenticated AFFiNE account in the app's **Created by**
  216. property, including semantic pages, template instances, and workspace welcome pages.
  217. Existing creator records are preserved; older pages are not backfilled.
  218. New database rows also record the authenticated AFFiNE account and creation time,
  219. including rows composed from intent or inserted as paragraph blocks. Editing or
  220. moving existing rows preserves their creation metadata; older rows are not backfilled.
  221. Use `AFFINE_TOOL_PROFILE=read_only`, `core`, or `authoring` when a deployment should expose a smaller surface than the complete `full` default. This is the recommended path for hosted, browser-connected, or least-privilege deployments because it reduces agent choice overload while keeping the full tool catalog available as an opt-in surface. You can also combine profiles with `AFFINE_DISABLED_GROUPS` such as `docs.database`, `destructive`, or `admin` for finer control.
  222. Full-note replacement with `replace_doc_with_markdown` is destructive and requires `full` without disabling the `destructive` group. `core` and `authoring` retain incremental editing through `append_markdown`, `update_block`, and `update_blocks`.
  223. For the grouped catalog, notes, and operational caveats, see [docs/tool-reference.md](docs/tool-reference.md).
  224. ## Documentation Map
  225. | Document | Purpose |
  226. | --- | --- |
  227. | [docs/getting-started.md](docs/getting-started.md) | First-run setup paths and verification |
  228. | [docs/client-setup.md](docs/client-setup.md) | Client-specific configuration snippets and tips |
  229. | [docs/configuration-and-deployment.md](docs/configuration-and-deployment.md) | Environment variables, auth modes, Docker, HTTP mode, and deployment guidance |
  230. | [docs/workflow-recipes.md](docs/workflow-recipes.md) | End-to-end workflows and example tool sequences |
  231. | [docs/tool-reference.md](docs/tool-reference.md) | Tool catalog grouped by domain |
  232. | [docs/edgeless-canvas-cookbook.md](docs/edgeless-canvas-cookbook.md) | Edgeless canvas layout helpers and surface elements, worked end-to-end |
  233. | [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor workflow |
  234. | [SECURITY.md](SECURITY.md) | Security reporting |
  235. ## Verify Your Setup
  236. Useful CLI commands:
  237. - `affine-mcp status` - test the effective configuration
  238. - `affine-mcp status --json` - machine-readable status output
  239. - `affine-mcp doctor` - diagnose config and connectivity issues
  240. - `affine-mcp workspaces [--json]` - list accessible workspaces by name and mark the default
  241. - `affine-mcp workspace [id]` - validate and set the local default workspace
  242. - `affine-mcp show-config` - print the effective config with secrets redacted
  243. - `affine-mcp config-path` - print the config file path
  244. - `affine-mcp snippet <claude|cursor|codex|all> [--env]` - generate ready-to-paste client config
  245. - `affine-mcp logout` - remove stored credentials
  246. Core configuration uses `environment > saved config > defaults`. HTTP body/session
  247. limits, proxy settings, WebSocket timeouts, and the HTTP compatibility escape
  248. hatches are environment-only runtime flags; they are not read from the saved
  249. `KEY=value` file. See [configuration precedence and environment scope](docs/configuration-and-deployment.md#configuration-precedence).
  250. For a self-hosted deployment with a non-standard GraphQL route, use
  251. `affine-mcp login --graphql-path /your/graphql/path` or set
  252. `AFFINE_GRAPHQL_PATH`; `show-config --json` prints the exact resolved
  253. `graphqlEndpoint` without exposing secrets. Generated workspace and document URLs
  254. use the configured AFFiNE base URL, so a custom GraphQL path does not become part
  255. of a browser link.
  256. For common failures, see:
  257. - [docs/getting-started.md#common-first-run-failures](docs/getting-started.md#common-first-run-failures)
  258. - [docs/configuration-and-deployment.md#deployment-checklist](docs/configuration-and-deployment.md#deployment-checklist)
  259. ## Security and Scope
  260. - Never commit passwords, session cookies, or compatible bearer tokens
  261. - Use a dedicated least-privilege AFFiNE account for unattended deployments
  262. - Email/password HTTP sessions share one login and never fall back to anonymous backend requests after authentication failure
  263. - Use HTTPS for non-local deployments
  264. - Keep remote HTTP MCP listeners authenticated; bearer mode refuses a non-loopback bind without `AFFINE_MCP_HTTP_TOKEN`
  265. - Send MCP bearer tokens in the `Authorization` header, never in the URL
  266. - Re-run `affine-mcp login` when a saved browser session expires
  267. - For GUI clients, verify `command -v affine-mcp` and `command -v node`; an absolute
  268. script path does not fix a `#!/usr/bin/env node` shebang when the GUI process has
  269. no Node.js directory in `PATH`. See [GUI client PATH troubleshooting](docs/client-setup.md#gui-client-path-troubleshooting).
  270. - Restrict exposed tools with `AFFINE_DISABLED_GROUPS` and `AFFINE_DISABLED_TOOLS` for least-privilege setups
  271. - Treat OAuth mode as a shared AFFiNE service-account deployment: it defaults to `read_only`, and write-capable profiles require `AFFINE_OAUTH_ALLOW_SERVICE_WRITES=true`
  272. - Use `/healthz` and `/readyz` when running the HTTP server behind a container platform or load balancer
  273. - Set HTTP body, session, idle, and shutdown limits explicitly for high-volume deployments
  274. ## Development
  275. Run the main quality gates before opening a PR:
  276. ```bash
  277. npm run ci
  278. ```
  279. Additional validation:
  280. - `npm test` verifies tool metadata, test-suite coverage, and the fast regression suite without requiring a live AFFiNE instance
  281. - `npm run test:comprehensive` boots a local Docker AFFiNE stack and validates the tool surface
  282. - `npm run test:e2e` runs Docker, MCP, and Playwright together
  283. - `npm run test:playwright` runs the Playwright suite only
  284. - Focused runners for the new high-level tool surface include `npm run test:create-placement`, `npm run test:capabilities-fidelity`, `npm run test:native-template`, `npm run test:mutation-ack`, `node tests/test-database-intent.mjs`, `node tests/test-semantic-page-composer.mjs`, `node tests/test-structured-receipts.mjs`, `node tests/test-organize-tools.mjs`, and `node tests/test-supporting-tools.mjs`
  285. Live tests can mutate or delete AFFiNE data. They allow loopback targets by
  286. default and refuse non-loopback targets unless the disposable target is
  287. explicitly enabled and confirmed as documented in `CONTRIBUTING.md`. Never run
  288. them against production.
  289. Local clone flow:
  290. ```bash
  291. git clone https://github.com/dawncr0w/affine-mcp-server.git
  292. cd affine-mcp-server
  293. npm install
  294. npm run build
  295. node dist/index.js
  296. ```
  297. ## Release Notes
  298. - [CHANGELOG.md](CHANGELOG.md)
  299. - [RELEASE_NOTES.md](RELEASE_NOTES.md)
  300. - [GitHub Releases](https://github.com/dawncr0w/affine-mcp-server/releases)
  301. ## License
  302. MIT License - see [LICENSE](LICENSE).
  303. ## Support
  304. - Open an issue on [GitHub](https://github.com/dawncr0w/affine-mcp-server/issues)
  305. - Review AFFiNE product documentation at [docs.affine.pro](https://docs.affine.pro)
  306. ## Acknowledgments
  307. - Built for the [AFFiNE](https://affine.pro) knowledge base platform
  308. - Uses the [Model Context Protocol](https://modelcontextprotocol.io) specification
  309. - Powered by [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.