Affine MCP Server

What is Affine MCP Server about?

Affine MCP Server provides a command‑line MCP server that bridges AFFiNE knowledge‑base instances (self‑hosted or cloud) with AI assistants. It exposes workspace and document operations, comment handling, version history, user management, notifications, and blob storage through standardized MCP tools, enabling AI models to read, create, edit, and organize AFFiNE content directly.

How to use Affine MCP Server?

Install / Run – the most convenient way is using npx without a global install:
```
npx -y -p affine-mcp-server affine-mcp -- --version
```
The command installs the package temporarily, then runs the affine-mcp binary which starts the MCP server on stdio.
Configure – set required environment variables before launching:
- AFFINE_BASE_URL – base URL of your AFFiNE instance.
- Authentication (choose one):
  - AFFINE_API_TOKEN – personal access token (preferred for speed).
  - AFFINE_COOKIE – session cookies.
  - AFFINE_EMAIL and AFFINE_PASSWORD – fallback email/password login. Optional variables: AFFINE_GRAPHQL_PATH, AFFINE_WORKSPACE_ID, AFFINE_LOGIN_AT_START (async by default).
Register with an AI client – e.g., Claude Desktop or Codex CLI, by adding the server definition to the client’s MCP configuration (JSON snippet shown in the README).

Key features of Affine MCP Server

Workspace management: list, get, create (with initial doc), update, delete.
Document tools (WebSocket‑based): list, get, publish/revoke, create, append paragraph, append slash‑command style blocks (heading, list, todo, code, divider, quote), delete.
Comments: full CRUD plus resolve.
Version history: list revisions.
User & token handling: current user info, sign‑in, profile/settings updates, generate/revoke personal access tokens.
Notifications: list and mark all as read.
Blob storage: upload, delete, cleanup.
31 canonical tools with strict manifest validation via CI.
Zero‑latency authentication when using token or cookie.
Cross‑platform CLI (global install, npx, or local clone).

Use cases of Affine MCP Server

AI‑assisted knowledge base editing – let Claude, Codex, or custom assistants create and update AFFiNE docs on‑the‑fly.
Automated documentation pipelines – generate release notes, meeting minutes, or project outlines directly in AFFiNE.
Comment moderation bots – scan, reply, and resolve comments programmatically.
Version‑controlled content generation – track AI‑generated changes via version history tools.
Secure internal tooling – expose AFFiNE data to internal AI agents without exposing HTTP APIs.

FAQ from the Affine MCP Server

Do I need to install the package globally? No. Using npx -y -p affine-mcp-server affine-mcp runs the server without a permanent install.
Which authentication method is fastest? Providing AFFINE_API_TOKEN (or AFFINE_COOKIE) avoids the async login step and gives instant access.
Can I run the server on Windows/macOS/Linux? Yes, it is a Node.js 18+ application and works on any OS with a supported Node runtime.
What if my password contains special characters like !? Quote the value in the shell or place it in a JSON config (as shown for Claude Desktop) to prevent shell expansion.
How does the server communicate with the AI client? Through stdio (stdin/stdout) following the Model Context Protocol, which is compatible with Claude Desktop and Codex CLI.
Is there a way to test tool manifest consistency? Run npm run test:tool-manifest locally; CI enforces the same check.
Can I customize the GraphQL endpoint? Yes, set AFFINE_GRAPHQL_PATH (default /graphql).

A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted or cloud). It exposes AFFiNE workspaces and documents to AI assistants over stdio.

Overview

Purpose: Manage AFFiNE workspaces and documents through MCP
Transport: stdio only (Claude Desktop / Codex compatible)
Auth: Token, Cookie, or Email/Password (priority order)
Tools: 31 focused tools with WebSocket-based document editing
Status: Active

New in v1.3.0: Added append_block for slash-command style blocks (heading/list/todo/code/divider/quote), removed duplicated aliases/non-core tools, and added CI + manifest quality gates.

Features

Workspace: create (with initial doc), read, update, delete
Documents: list/get/publish/revoke + create/append paragraph/delete (WebSocket‑based)
Comments: full CRUD and resolve
Version History: list
Users & Tokens: current user, sign in, profile/settings, and personal access tokens
Notifications: list and mark as read
Blob storage: upload/delete/cleanup

Requirements

Node.js 18+
An AFFiNE instance (self‑hosted or cloud)
Valid AFFiNE credentials or access token

Installation

# Global install (recommended)
npm i -g affine-mcp-server

# Or run ad‑hoc via npx (no install)
npx -y -p affine-mcp-server affine-mcp -- --version

The package installs a CLI named affine-mcp that runs the MCP server over stdio.

Note: From v1.2.2+ the CLI wrapper (bin/affine-mcp) ensures Node runs the ESM entrypoint, preventing shell from misinterpreting JS.

Configuration

Configure via environment variables (shell or app config). .env files are no longer recommended.

Required: AFFINE_BASE_URL
Auth (choose one): AFFINE_API_TOKEN | AFFINE_COOKIE | AFFINE_EMAIL + AFFINE_PASSWORD
Optional: AFFINE_GRAPHQL_PATH (default /graphql), AFFINE_WORKSPACE_ID, AFFINE_LOGIN_AT_START (async default, sync to block)

Authentication priority:

AFFINE_API_TOKEN → 2) AFFINE_COOKIE → 3) AFFINE_EMAIL + AFFINE_PASSWORD

Quick Start

Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "affine": {
      "command": "affine-mcp",
      "env": {
        "AFFINE_BASE_URL": "https://your-affine-instance.com",
        "AFFINE_EMAIL": "you@example.com",
        "AFFINE_PASSWORD": "secret!",
        "AFFINE_LOGIN_AT_START": "async"
      }
    }
  }
}

Tips

Prefer AFFINE_COOKIE or AFFINE_API_TOKEN for zero‑latency startup.
If your password contains ! (zsh history expansion), wrap it in single quotes in shells or use the JSON config above.

Codex CLI

Global install path (fastest)
- npm i -g affine-mcp-server
- codex mcp add affine --env AFFINE_BASE_URL=https://your-affine-instance.com --env 'AFFINE_EMAIL=you@example.com' --env 'AFFINE_PASSWORD=secret!' --env AFFINE_LOGIN_AT_START=async -- affine-mcp
Use npx (no global install)
- codex mcp add affine --env AFFINE_BASE_URL=https://your-affine-instance.com --env 'AFFINE_EMAIL=you@example.com' --env 'AFFINE_PASSWORD=secret!' --env AFFINE_LOGIN_AT_START=async -- npx -y -p affine-mcp-server affine-mcp
Token or cookie (no startup login)
- Token: codex mcp add affine --env AFFINE_BASE_URL=https://... --env AFFINE_API_TOKEN=... -- affine-mcp
- Cookie: codex mcp add affine --env AFFINE_BASE_URL=https://... --env "AFFINE_COOKIE=affine_session=...; affine_csrf=..." -- affine-mcp

Notes

MCP name: affine
Command: affine-mcp
Environment: AFFINE_BASE_URL + one auth method (AFFINE_API_TOKEN | AFFINE_COOKIE | AFFINE_EMAIL/AFFINE_PASSWORD)

Available Tools

Workspace

list_workspaces – list all workspaces
get_workspace – get workspace details
create_workspace – create workspace with initial document
update_workspace – update workspace settings
delete_workspace – delete workspace permanently

Documents

list_docs – list documents with pagination
get_doc – get document metadata
publish_doc – make document public
revoke_doc – revoke public access
create_doc – create a new document (WebSocket)
append_paragraph – append a paragraph block (WebSocket)
append_block – append slash-command style blocks (heading/list/todo/code/divider/quote)
delete_doc – delete a document (WebSocket)

Comments

list_comments, create_comment, update_comment, delete_comment, resolve_comment

Version History

list_histories

Users & Tokens

current_user, sign_in, update_profile, update_settings
list_access_tokens, generate_access_token, revoke_access_token

Notifications

list_notifications, read_all_notifications

Blob Storage

upload_blob, delete_blob, cleanup_blobs

Use Locally (clone)

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

# Or expose as a global CLI for Codex/Claude without publishing
npm link
# Now use `affine-mcp` like a global binary

Quality Gates

npm run build
npm run test:tool-manifest
npm run pack:check

tool-manifest.json is the source of truth for publicly exposed tool names.
CI validates that registerTool(...) declarations match the manifest exactly.

Troubleshooting

Authentication

Email/Password: ensure your instance allows password auth and credentials are valid
Cookie: copy cookies (e.g., affine_session, affine_csrf) from the browser DevTools after login
Token: generate a personal access token; verify it hasn't expired
Startup timeouts: v1.2.2+ includes a CLI wrapper fix and default async login to avoid blocking the MCP handshake. Set AFFINE_LOGIN_AT_START=sync only if needed.

Connection

Confirm AFFINE_BASE_URL is reachable
GraphQL endpoint default is /graphql
Check firewall/proxy rules; verify CORS if self‑hosted

Security Considerations

Never commit .env with secrets
Prefer environment variables in production
Rotate access tokens regularly
Use HTTPS
Store credentials in a secrets manager

Version History

1.3.0 (2026‑02‑13)

Added append_block for slash-command style editing (heading/list/todo/code/divider/quote)
Tool surface simplified to 31 canonical tools (duplicate aliases removed)
Added CI + manifest parity verification (npm run test:tool-manifest, npm run ci)
Added open-source community health docs and issue/PR templates

1.2.2 (2025‑09‑18)

CLI wrapper added to ensure Node runs ESM entry (bin/affine-mcp), preventing shell mis-execution
Docs cleaned: use env vars via shell/app config; .env file no longer recommended
MCP startup behavior unchanged from 1.2.1 (async login by default)

1.2.1 (2025‑09‑17)

Default to asynchronous email/password login after MCP stdio handshake
New AFFINE_LOGIN_AT_START env (async default, sync to block at startup)
Expanded docs for Codex/Claude using npm, npx, and local clone

1.2.0 (2025‑09‑16)

WebSocket-based document tools: create_doc, append_paragraph, delete_doc (create/edit/delete now supported)
Tool aliases introduced at the time (affine_* + non-prefixed names). They were removed later to reduce duplication.
ESM resolution: NodeNext; improved build stability
CLI binary: affine-mcp for easy npm i -g usage

1.1.0 (2025‑08‑12)

Fixed workspace creation with initial documents (UI accessible)
30+ tools, simplified tool names
Improved error handling and authentication

1.0.0 (2025‑08‑12)

Initial stable release
Basic workspace and document operations
Full authentication support

Contributing

Contributions are welcome!

Read CONTRIBUTING.md
Run npm run ci locally before opening PR
Keep tool changes synced with tool-manifest.json
Use issue/PR templates in .github/

Community Health

Code of Conduct: CODE_OF_CONDUCT.md
Security policy: SECURITY.md
Contributing guide: CONTRIBUTING.md

License

MIT License - see LICENSE file for details

Support

For issues and questions:

Open an issue on GitHub
Check AFFiNE documentation at https://docs.affine.pro

Author

dawncr0w - GitHub

Acknowledgments

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

Affine MCP Server