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.

Version MCP SDK CI License

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 token, cookie, and email/password authentication
• Exposes 95 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 Cloud requires API-token-based access for MCP usage; programmatic email/password sign-in is blocked by Cloudflare

New in v2.5.0: Added MCP behavior annotations and Glama metadata so clients and MCP directories can classify tools more safely.

Choose Your Path

Goal	Start here
Set up a local stdio server with the least friction	docs/getting-started.md
Run the server in Docker or another OCI runtime	docs/getting-started.md#path-c-run-from-the-docker-image
Configure Claude Code, Claude Desktop, Codex CLI, or Cursor	docs/client-setup.md
Run the server remotely over HTTP or behind OAuth	docs/configuration-and-deployment.md
Lock down tool exposure for least-privilege deployments	docs/configuration-and-deployment.md#least-privilege-tool-exposure
Learn common AFFiNE workflows and tool sequences	docs/workflow-recipes.md
Browse the tool catalog by domain	docs/tool-reference.md

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 AFFINE_API_TOKEN=ut_your_token \
  -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 ~/.config/affine-mcp/config with mode 600.

• For AFFiNE Cloud, use an API token from Settings -> Integrations -> MCP Server
• For self-hosted AFFiNE, you can use either an API token or email/password

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

Target	Transport	Recommended auth	Recommended path
Claude Code	stdio	Saved config or API token	docs/client-setup.md#claude-code
Claude Desktop	stdio	Saved config or API token	docs/client-setup.md#claude-desktop
Codex CLI	stdio	Saved config or API token	docs/client-setup.md#codex-cli
Cursor	stdio	Saved config or API token	docs/client-setup.md#cursor
Containerized remote deployment	HTTP	Bearer token or OAuth	docs/getting-started.md#path-c-run-from-the-docker-image
Remote MCP clients	HTTP	Bearer token or OAuth	docs/configuration-and-deployment.md#http-mode
AFFiNE Cloud	stdio or HTTP	API token	docs/configuration-and-deployment.md#auth-strategy-matrix
Self-hosted AFFiNE	stdio or HTTP	API token, cookie, or email/password	docs/configuration-and-deployment.md#auth-strategy-matrix

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 tokens: current user, sign-in, profile/settings, personal access tokens
• 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

Document	Purpose
docs/getting-started.md	First-run setup paths and verification
docs/client-setup.md	Client-specific configuration snippets and tips
docs/configuration-and-deployment.md	Environment variables, auth modes, Docker, HTTP mode, and deployment guidance
docs/workflow-recipes.md	End-to-end workflows and example tool sequences
docs/tool-reference.md	Tool catalog grouped by domain
docs/edgeless-canvas-cookbook.md	Edgeless canvas layout helpers and surface elements, worked end-to-end
CONTRIBUTING.md	Contributor workflow
SECURITY.md	Security reporting

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

For common failures, see:

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

Security and Scope

• Never commit secrets or long-lived tokens
• Prefer API tokens over cookies or passwords in production
• Use HTTPS for non-local deployments
• Rotate access tokens regularly
• Restrict exposed tools with AFFINE_DISABLED_GROUPS and AFFINE_DISABLED_TOOLS for least-privilege setups
• Use /healthz and /readyz when running the HTTP server behind a container platform or load balancer

Development

Run the main quality gates before opening a PR:

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

Additional validation:

• 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, 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

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