# affine-mcp-server — AFFiNE Docs & Database MCP
> AFFiNE MCP Server exposes AFFiNE workspaces to Claude Code/Cursor via MCP (stdio/HTTP), with auth and least-privilege tool profiles.
## Install
Merge the JSON below into your `.mcp.json`:
## Quick Use
```bash
# Install CLI
npm i -g affine-mcp-server
affine-mcp --version
# Optional: run via npx
npx -y -p affine-mcp-server affine-mcp -- --version
```
```bash
# Docker (HTTP transport)
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
```
## Intro
AFFiNE MCP Server connects AI assistants to AFFiNE workspaces, documents, and databases through a stable MCP tool surface over stdio or HTTP. It targets Claude Code/Codex CLI/Cursor setups where you want least-privilege, auditable access to your knowledge base.
**Best for:** teams using AFFiNE as a docs + database knowledge hub and want to let coding agents retrieve/update content safely
**Works with:** Claude Code/Cursor/Codex CLI, Node.js (CLI), Docker (optional), AFFiNE Cloud or self-hosted AFFiNE
**Setup time:** 15–25 minutes
### Key facts (verified)
- Version badge in README shows 2.0.0.
- README states an 84-tool public MCP surface and least-privilege profiles.
- GitHub: 165 stars · 56 forks; pushed 2026-05-11 (GitHub API verified).
## Main
Treat this server like an integration boundary: start with read-only or core profiles, then widen tool exposure only when you have specific AFFiNE automation needs. For hosted usage, prefer HTTP transport with a strong bearer token and keep the token outside your project repo.
If you want a minimal Claude client config, use the Docker + HTTP `/mcp` endpoint shown in the README and set headers per client.
### README excerpt (verbatim)
# 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 84 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
### FAQ
**Q: Is this compatible with AFFiNE Cloud?**
A: Yes—README states it supports AFFiNE Cloud and self-hosted deployments; Cloud uses API-token-based access.
**Q: Does it support stdio and HTTP transports?**
A: Yes—README describes stdio (default) and HTTP `/mcp` transport.
**Q: How do I reduce risk?**
A: Restrict tool exposure (least privilege), keep tokens out of repos, and prefer read-only for initial rollout.
## Source & Thanks
> Source: https://github.com/DAWNCR0W/affine-mcp-server
> License: MIT
> GitHub stars: 165 · forks: 56
---
## 快速使用
```bash
# 安装 CLI
npm i -g affine-mcp-server
affine-mcp --version
# 或用 npx 临时运行
npx -y -p affine-mcp-server affine-mcp -- --version
```
```bash
# Docker（HTTP 传输）
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
```
## 简介
AFFiNE MCP Server 通过 MCP（stdio/HTTP）把 AI 助手连接到 AFFiNE 的工作区、文档与数据库工具面。适合需要最小权限、可审计地让 Claude Code/Codex CLI/Cursor 访问知识库的团队。
**最适合：** 用 AFFiNE 管理文档与数据库，并希望让编码 Agent 安全检索/写入内容的团队
**适配：** Claude Code/Cursor/Codex CLI、Node.js（CLI）、Docker（可选）、AFFiNE Cloud 或自托管
**配置时间：** 15–25 分钟
### 关键事实（已验证）
- README 版本徽章显示 2.0.0。
- README 提到公开 MCP 工具面为 84 个，并提供最小权限 profile。
- GitHub：165 stars · 56 forks；最近更新 2026-05-11（GitHub API 验证）。
## 正文
把它当作“集成边界”来用：先从只读/核心权限开始，再按真实需求逐步放开工具。托管场景优先用 HTTP 传输 + 强随机 Bearer token，并把 token 放在环境变量或私密配置中，不要进仓库。
最小化配置可以直接参考 README 里的 Docker + HTTP `/mcp` 端点示例，并按客户端配置 headers。
### README 原文节选（verbatim）
# 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 84 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
### FAQ
**它支持 AFFiNE Cloud 吗？**
答：支持。README 写明支持 AFFiNE Cloud 与自托管；Cloud 场景通常使用 API token 访问。
**支持 stdio 和 HTTP 吗？**
答：支持。README 描述了默认 stdio 与 HTTP `/mcp` 传输。
**如何降低风险？**
答：用最小权限限制工具面、token 不入库，先从只读开始再逐步放开。
## 来源与感谢
> Source: https://github.com/DAWNCR0W/affine-mcp-server
> License: MIT
> GitHub stars: 165 · forks: 56
---
Source: https://tokrepo.com/en/workflows/affine-mcp-server-affine-docs-database-mcp
Author: MCP Hub