AFFiNE MCP Server: AFFiNE notes and databases for agents
AFFiNE MCP Server
An MCP server for AFFiNE: the agent searches, creates and edits documents, databases and comments in cloud or self-hosted AFFiNE
- 315 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent gets the rights of your AFFiNE account: it can create, change and delete documents and databases
- A password or session cookie is stored in a settings file on your machine
Install
- Works in
Manual install
npm i -g affine-mcp-server && affine-mcp loginAfter sign-in, add an affine entry with the command affine-mcp to the MCP config.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent gets the rights of your AFFiNE account: it can create, change and delete documents and databases
- A password or session cookie is stored in a settings file on your machine
This is third-party code. Review the repository files before installing.
What it does
AFFiNE MCP Server opens AFFiNE workspaces to an agent: documents, databases and comments, plus version history, notifications and attachments. The server runs over stdio for Claude Code, Codex CLI, Cursor and Claude Desktop, or over HTTP at /mcp for remote clients. Documents are created from Markdown with headings, code and math. A page can be composed from semantic parts or from an AFFiNE template, and edited block by block. In databases the server works with rows and columns. Optional revisions reject edits made on top of a stale document version, and concurrent writes to one workspace are queued by the server. First setup goes through `affine-mcp login`. The status and doctor commands handle diagnostics, and snippet prints a ready config fragment for Claude, Cursor or Codex. The tool set can be narrowed with a profile, and groups can be disabled through environment variables.
Who it is for. For people who keep notes, documentation and databases in AFFiNE and want Claude Code, Codex or Cursor to read and write them.
Good fit when
- The agent must find and read documents from your AFFiNE knowledge base
- You want to assemble a document in AFFiNE from the agent's results as Markdown with headings and math
- You need to maintain an AFFiNE database: add rows, change values, inspect the schema
- Several agents write to one workspace and you want revisions that reject an edit on top of a stale version
- You are deploying the server on a remote machine in Docker with token or OAuth auth
Not a fit when
- Your notes live only in browser-local storage: the server sees only workspaces on an AFFiNE server
- You need AFFiNE Cloud sign-in by email and password from a script
- You need token management for AFFiNE: personal access tokens were removed in 0.27 and later, and there are no tools for them
- You cannot give the agent permission to delete documents
Example request
Find the documents about release 2.0 in my AFFiNE and create a new document with a rollout plan as a checklist.MCP
- Transport
- stdio, http
- Authentication
- key is optional
Environment variables
AFFINE_BASE_URL- The address of your AFFiNE. AFFiNE Cloud by default.
AFFINE_EMAIL- Account email for signing in to a self-hosted server.
AFFINE_PASSWORDsecret- Account password for signing in to a self-hosted server.
AFFINE_WORKSPACE_ID- The default workspace.
AFFINE_TOOL_PROFILE- Tool profile: read_only, core, authoring or full.
Limitations
Node.js 20.18.1 or newer is required. AFFiNE Cloud needs a browser session: you paste the Cookie header from an open tab during setup. The session expires, so sign-in has to be repeated. Email and password work for a self-hosted server.
The delete_doc tool removes page metadata and requests content deletion, yet some AFFiNE servers retain the content. trash_doc offers recoverable cleanup. If a write's timestamp cannot be confirmed, the server retries up to three times. When there is still no confirmation, inspect the saved document and do not repeat the edit.
How to disable. Remove the affine entry from the client config and restart it. Saved credentials are cleared with `affine-mcp logout`. For Docker, stop the container.
FAQ
How do I connect AFFiNE MCP Server to Claude Code?
Run npm i -g affine-mcp-server and affine-mcp login, then add an affine entry to the config with the command affine-mcp. The status and doctor commands help verify the result.
Does the server work with AFFiNE Cloud?
Yes, but sign-in goes through a browser session. Sign in to AFFiNE in a browser and paste the request's Cookie header during affine-mcp login. Email and password sign-in from a script is blocked by Cloudflare on the cloud; it works for a self-hosted server.
How do I limit the agent's access to AFFiNE?
Set AFFINE_TOOL_PROFILE to read_only, core or authoring. Groups can be disabled with AFFINE_DISABLED_GROUPS and single tools with AFFINE_DISABLED_TOOLS. Full document replacement through replace_doc_with_markdown is available only in the full profile.
How do I run the server in Docker?
Run the ghcr.io/dawncr0w/affine-mcp-server image with MCP_TRANSPORT=http, AFFINE_BASE_URL, AFFINE_EMAIL, AFFINE_PASSWORD, AFFINE_MCP_AUTH_MODE=bearer and AFFINE_MCP_HTTP_TOKEN and publish port 3000. The client connects to http://localhost:3000/mcp with an Authorization: Bearer header.
What if the AFFiNE session expires?
Run affine-mcp login again. To avoid repeating it you can save the email and password with affine-mcp login --save-credentials, and the server renews the session itself. The password lands in a settings file with mode 600, so create a dedicated account.
Discussion
No questions or reviews yet.
Related
MCP serversOfficial Anytype MCP server: an agent searches, creates and edits objects, lists and types in your knowledge base
A Notion MCP server: the agent searches, reads, queries and updates workspace pages and databases
An MCP server that lets an agent work on your computer: terminal and long-running processes, file search and edits, Excel, PDF and DOCX
Minutes
minutes
A local-first MCP server for meeting memory: on-device recording and transcription into Markdown, searchable from Claude Code, Codex, Cursor and any MCP client
Notion MCP (awkoy)
Notion MCP Server (awkoy)
Notion MCP on a token: an agent searches pages, runs databases, edits blocks and comments through three tools and 47 operations, with no manual sign-in
Official local MCP server for the Notion API: search, read and edit pages as Markdown, and work with databases
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| AFFiNE MCP Server: AFFiNE notes and databases for agents (this entry) | no | key is optional | 315 | |
| Obsidian MCP Server | no | API key | 700 | works with a local Obsidian vault |
| Notion MCP (awkoy) | no | API key | 179 | connects to Notion with an integration token, with a different page and database model |
README in short
The documentation is split by task, from a quick install to a tool reference by group. A separate section covers safety for shared deployments, from a dedicated account to the /healthz and /readyz health checks.