affine

This MCP server integrates AFFiNE workspaces and documents with AI assistants. It exposes AFFiNE resources over MCP using the standard AFFiNE MCP server tooling, primarily via a local stdio channel by default, with an optional HTTP /mcp endpoint for remote deployments. The server supports 43 tools for workspace and document management, including creating and updating workspaces, listing and retrieving documents, publishing and revoking documents, markdown import/export, tag handling, database block workflows, comment management, version history, user and token management, notifications, and blob storage operations. To run locally, install the global affine-mcp-server CLI and start the server; the server will read credentials from the AFFiNE MCP config stored by the affine-mcp CLI. For remote deployments, configure the HTTP transport and provide the necessary AFFINE_BASE_URL and authentication tokens or cookies so clients can connect over HTTP at the /mcp path.

Prerequisites:

• Node.js 18+ and npm
• Access to an AFFiNE instance (self-hosted or cloud) with valid credentials or API token

Installation steps:

1. Install the CLI globally (recommended):

npm i -g affine-mcp-server

2. Start the server (stdin mode):

affine-mcp

This runs the MCP server over stdio. Alternatively you can run ad-hoc via npx without installation:

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

3. Optional: verify installation and credentials by performing a login to populate ~/.config/affine-mcp/config. The CLI login stores credentials securely for the MCP server to read automatically.

Configuration via CLI (interactive login):

affine-mcp login

Follow prompts to connect to your AFFiNE instance and generate an API token for MCP access. Credentials are stored in a secure config file and read automatically by the MCP server.

Configuration via environment variables (alternative):

• AFFINE_BASE_URL is required
• Auth: AFFINE_API_TOKEN or AFFINE_COOKIE or AFFINE_EMAIL + AFFINE_PASSWORD
• Optional: AFFINE_GRAPHQL_PATH, AFFINE_WORKSPACE_ID, AFFINE_LOGIN_AT_START

Example using environment variables (replace with real values):

export AFFINE_BASE_URL=https://app.affine.pro
export AFFINE_API_TOKEN=ut_xxx
export AFFINE_GRAPHQL_PATH=/graphql
# Start the server in stdio mode or configure your MCP client to connect to the CLI's stdio channel

Tips:

• Prefer affine-mcp login or AFFINE_API_TOKEN for zero-latency startup.
• If using a password in shells, consider quoting to avoid shell history expansion issues.
• For remote HTTP deployments, set MCP_TRANSPORT=http and protect /mcp with a strong token (AFFINE_MCP_HTTP_TOKEN) and origin controls (AFFINE_MCP_HTTP_ALLOWED_ORIGINS).
• When using Cloud AFFiNE, avoid Cloudflare blocks by using token-based authentication or the login flow which handles token creation automatically.
• The README notes 43 tools are available; familiarize yourself with the MCP SDK documentation to leverage WebSocket-based document editing and workspace management features.
• The CLI wrapper ensures Node runs the ESM entrypoint to prevent shell misinterpretation of JS modules.