AFFiNE MCP Server

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.

Table of Contents

• Overview
• Choose Your Path
• Quick Start
• Compatibility Matrix
• Tool Surface
• Documentation Map
• Verify Your Setup
• Security and Scope
• Development
• Release Notes
• License
• Support

Overview

AFFiNE MCP Server is designed for three common scenarios:

• Run a local stdio MCP server for Claude Code, Codex CLI, Cursor, or Claude Desktop
• Expose a remote HTTP MCP endpoint for hosted or browser-connected clients
• Automate AFFiNE workspace, document, database, organization, and comment workflows through a stable MCP tool surface

Highlights:

• Supports AFFiNE Cloud and self-hosted AFFiNE instances
• Supports stdio and HTTP transports
• Supports session-cookie and email/password authentication, plus compatible bearer tokens for older deployments
• Exposes 92 canonical MCP tools backed by AFFiNE GraphQL and WebSocket APIs
• Includes semantic page composition, native template instantiation, database intent composition, capability and fidelity reporting, and workspace blueprint helpers
• Includes Docker images, health probes, and end-to-end test coverage

Scope boundaries:

• This server can access only server-backed AFFiNE workspaces
• Browser-local workspaces stored only in local storage are not available through AFFiNE server APIs
• AFFiNE 0.27+ removed the legacy personal-access-token GraphQL API; this server no longer exposes token-management tools
• AFFiNE Cloud requires browser-session authentication for this external GraphQL integration; programmatic email/password sign-in is blocked by Cloudflare

New in v3.0.1: Markdown import/export now preserves AFFiNE inline LinkedPage references for safe round-tripping.

Choose Your Path

Quick Start

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 [email protected] \
  -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:latest

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.

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.

• 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

4. Register the server with your client

Claude Code project config:

{
  "mcpServers": {
    "affine": {
      "command": "affine-mcp"
    }
  }
}

Codex CLI:

codex mcp add affine -- affine-mcp

More client-specific setup is in docs/client-setup.md.

5. Verify the connection

affine-mcp status
affine-mcp doctor

If you want to expose the server remotely over HTTP instead of stdio, start with docs/configuration-and-deployment.md.

Compatibility Matrix

Node.js 20 is the minimum supported runtime. CI validates the minimum runtime and the current Node.js release used by the npm publish workflow.

Tool Surface

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.

Domains:

• Workspace: create, inspect, update, delete, and traverse workspaces
• Organization: collections, collection-rule sync, workspace blueprints, and experimental organize or folder helpers
• 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
• Databases: create columns, add rows, update rows, inspect schema, and compose database structures from intent
• Comments: list, create, update, delete, and resolve
• History: version history listing
• Users and authentication: current user, sign-in, and profile/settings
• Notifications: list and mark notifications as read
• Blob storage: upload, delete, and cleanup blobs

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.

For the grouped catalog, notes, and operational caveats, see docs/tool-reference.md.

Documentation Map

Verify Your Setup

Useful CLI commands:

• affine-mcp status - test the effective configuration
• affine-mcp status --json - machine-readable status output
• affine-mcp doctor - diagnose config and connectivity issues
• affine-mcp show-config - print the effective config with secrets redacted
• affine-mcp config-path - print the config file path
• affine-mcp snippet <claude|cursor|codex|all> [--env] - generate ready-to-paste client config
• affine-mcp logout - remove stored credentials

status, doctor, and the server runtime use the same environment > saved config > defaults resolution. For a self-hosted deployment with a non-standard GraphQL route, use affine-mcp login --graphql-path /your/graphql/path or set AFFINE_GRAPHQL_PATH; show-config --json prints the exact resolved graphqlEndpoint without exposing secrets.

For common failures, see:

• docs/getting-started.md#common-first-run-failures
• docs/configuration-and-deployment.md#deployment-checklist

Security and Scope

• Never commit passwords, session cookies, or compatible bearer tokens
• Use a dedicated least-privilege AFFiNE account for unattended deployments
• Email/password HTTP sessions share one login and never fall back to anonymous backend requests after authentication failure
• Use HTTPS for non-local deployments
• Keep remote HTTP MCP listeners authenticated; bearer mode refuses a non-loopback bind without AFFINE_MCP_HTTP_TOKEN
• Send MCP bearer tokens in the Authorization header, never in the URL
• Re-run affine-mcp login when a saved browser session expires
• Restrict exposed tools with AFFINE_DISABLED_GROUPS and AFFINE_DISABLED_TOOLS for least-privilege setups
• 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
• Use /healthz and /readyz when running the HTTP server behind a container platform or load balancer
• Set HTTP body, session, idle, and shutdown limits explicitly for high-volume deployments

Development

Run the main quality gates before opening a PR:

npm run ci

Additional validation:

• npm test verifies tool metadata, test-suite coverage, and the fast regression suite without requiring a live AFFiNE instance
• npm run test:comprehensive boots a local Docker AFFiNE stack and validates the tool surface
• npm run test:e2e runs Docker, MCP, and Playwright together
• npm run test:playwright runs the Playwright suite only
• 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

Live tests can mutate or delete AFFiNE data. They allow loopback targets by default and refuse non-loopback targets unless the disposable target is explicitly enabled and confirmed as documented in CONTRIBUTING.md. Never run them against production.

Local clone flow:

git clone https://github.com/dawncr0w/affine-mcp-server.git
cd affine-mcp-server
npm install
npm run build
node dist/index.js

Release Notes

• CHANGELOG.md
• RELEASE_NOTES.md
• GitHub Releases

License

MIT License - see LICENSE.

Support

• Open an issue on GitHub
• Review AFFiNE product documentation at docs.affine.pro

Acknowledgments

• Built for the AFFiNE knowledge base platform
• Uses the Model Context Protocol specification
• Powered by @modelcontextprotocol/sdk