Affine Mcp Server

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.

[](https://github.com/dawncr0w/affine-mcp-server/releases) [](https://github.com/modelcontextprotocol/typescript-sdk) [](https://github.com/dawncr0w/affine-mcp-server/actions/workflows/ci.yml) [](LICENSE)

Table of Contents

• [Overview](#overview)
• [Choose Your Path](#choose-your-path)
• [Quick Start](#quick-start)
• [Compatibility Matrix](#compatibility-matrix)
• [Tool Surface](#tool-surface)
• [Documentation Map](#documentation-map)
• [Verify Your Setup](#verify-your-setup)
• [Security and Scope](#security-and-scope)
• [Development](#development)
• [Release Notes](#release-notes)
• [License](#license)
• [Support](#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.4.0: Added delete_tag for workspace tag cleanup and surfaced inTrash across document listing and hierarchy tools.

Choose Your Path

| Goal | Start here | | --- | --- | | Set up a local stdio server with the least friction | [docs/getting-started.md](docs/getting-started.md) | | 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) | | Configure Claude Code, Claude Desktop, Codex CLI, or Cursor | [docs/client-setup.md](docs/client-setup.md) | | Run the server remotely over HTTP or behind OAuth | [docs/configuration-and-deployment.md](docs/configuration-and-deployment.md) | | 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) | | Learn common AFFiNE workflows and tool sequences | [docs/workflow-recipes.md](docs/workflow-recipes.md) | | Browse the tool catalog by domain | [docs/tool-reference.md](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](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](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](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](docs/client-setup.md#claude-code) | | Claude Desktop | stdio | Saved config or API token | [docs/client-setup.md#claude-desktop](docs/client-setup.md#claude-desktop) | | Codex CLI | stdio | Saved config or API token | [docs/client-setup.md#codex-cli](docs/client-setup.md#codex-cli) | | Cursor | stdio | Saved config or API token | [docs/client-setup.md#cursor](docs/client-setup.md#cursor) | | 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) | | Remote MCP clients | HTTP | Bearer token or OAuth | [docs/configuration-and-deployment.md#http-mode](docs/configuration-and-deployment.md#http-mode) | | AFFiNE Cloud | stdio or HTTP | API token | [docs/configuration-and-deployment.md#auth-strategy-matrix](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](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.

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. 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](docs/tool-reference.md).

Documentation Map

| Document | Purpose | | --- | --- | | [docs/getting-started.md](docs/getting-started.md) | First-run setup paths and verification | | [docs/client-setup.md](docs/client-setup.md) | Client-specific configuration snippets and tips | | [docs/configuration-and-deployment.md](docs/configuration-and-deployment.md) | Environment variables, auth modes, Docker, HTTP mode, and deployment guidance | | [docs/workflow-recipes.md](docs/workflow-recipes.md) | End-to-end workflows and example tool sequences | | [docs/tool-reference.md](docs/tool-reference.md) | Tool catalog grouped by domain | | [docs/edgeless-canvas-cookbook.md](docs/edgeless-canvas-cookbook.md) | Edgeless canvas layout helpers and surface elements, worked end-to-end | | [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor workflow | | [SECURITY.md](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 [--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/getting-started.md#common-first-run-failures)
• [docs/configuration-and-deployment.md#deployment-checklist](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](CHANGELOG.md)
• [RELEASENOTES.md](RELEASENOTES.md)
• GitHub Releases

License

MIT License - see [LICENSE](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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DAWNCR0W
• Source: DAWNCR0W/affine-mcp-server
• License: MIT
• Homepage: https://glama.ai/mcp/servers/@DAWNCR0W/affine-mcp-server

Install and usage instructions live in the source repository linked above.