affine-mcp-server MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

8개 도메인(워크스페이스, 문서, DB, 댓글, 히스토리, 사용자, blob, 조직) 전반의 87개 툴
문서 검색 + 생성 + 게시
데이터베이스 작업 — 일반 문서뿐 아니라 구조화된 AFFiNE 데이터베이스
인증: API 토큰(권장), 쿠키, 이메일/비밀번호(셀프 호스팅만)
stdio + Docker 배포

라이브 데모

실제 사용 모습

affine.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "affine": {
      "command": "npx",
      "args": [
        "-y",
        "affine-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "affine": {
      "command": "npx",
      "args": [
        "-y",
        "affine-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "affine": {
      "command": "npx",
      "args": [
        "-y",
        "affine-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "affine": {
      "command": "npx",
      "args": [
        "-y",
        "affine-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "affine",
      "command": "npx",
      "args": [
        "-y",
        "affine-mcp-server"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "affine": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "affine-mcp-server"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add affine -- npx -y affine-mcp-server

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: affine-mcp-server

Claude에서 AFFiNE으로 빠른 메모 기록하기

👤 AFFiNE을 주 메모 도구로 쓰는 사용자 ⏱ ~5 min beginner

언제 쓸까: 대화 중에 컨텍스트 전환 없이 요점을 AFFiNE에 기록하고 싶을 때.

사전 조건

AFFiNE API 토큰 — AFFiNE Cloud: Settings > Integrations > MCP Server

흐름

워크스페이스 찾기

내 AFFiNE 워크스페이스 목록을 보여줘. 'Personal'에 쓰려고 해.✓ 복사됨

→ 워크스페이스 목록
문서 생성

'2026-04-14 meeting notes' 제목으로 [내용 붙여넣기]로 새 문서를 만들어줘. /Meetings 아래에 둬.✓ 복사됨

→ 문서 생성됨 + URL

결과: 채팅을 벗어나지 않고 AFFiNE에 메모.

함정

Cloud에서는 Cloudflare가 이메일/비밀번호 인증을 차단 — Cloud에서는 API 토큰을 쓰세요; 이메일/비밀번호는 셀프 호스팅에서만

외부 신호로부터 AFFiNE 데이터베이스에 행 추가하기

👤 AFFiNE 데이터베이스를 가벼운 CRM/트래커로 쓰는 지식 근로자 ⏱ ~10 min intermediate

언제 쓸까: 이메일에서 들어오는 뉴스레터 구독자를 'Contacts' AFFiNE DB에 기록하고 싶을 때.

흐름

DB 목록 조회

'Work' 워크스페이스의 데이터베이스를 보여줘.✓ 복사됨

→ DB 목록
행 추가

'Contacts' 데이터베이스에 행 추가: name='Jane Doe', email='[email protected]', source='Newsletter', date=today.✓ 복사됨

→ UUID와 함께 행 추가됨

결과: LLM이 주도하는 경량 CRM으로서의 AFFiNE.

함정

필드 타입이 DB 스키마와 맞아야 함 — describe-database류의 툴로 먼저 스키마를 확인하세요

AFFiNE 워크스페이스 전반을 검색하고 결과 요약하기

👤 문서가 많은 AFFiNE 파워 유저 ⏱ ~10 min beginner

언제 쓸까: 어딘가에 X에 대해 썼던 기억은 나는데 어디에 썼는지 모를 때.

흐름

검색

내 워크스페이스 전반에서 'series A process'를 검색해줘. 스니펫과 함께 상위 10개 문서를 보여줘.✓ 복사됨

→ 하이라이트가 붙은 문서 결과
요약

상위 3개 문서를 불러와 핵심 요점과 모순되는 부분을 요약해줘.✓ 복사됨

→ 문서 간 요약

결과: 내 메모에서 조직 지식이 드러남.

조합

다른 MCP와 조합해 10배 효율

affine + gmail-like + youtube-transcript

콘텐츠를 AFFiNE에 기록

이 영상을 요약해서 AFFiNE의 'Talks Notes' DB에 저장해줘.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
list_workspaces		AFFiNE 그래프 탐색	1 API call
search_documents	workspace_id, query, limit?	텍스트로 문서 찾기	1 API call
create_document	workspace_id, title, content, parent_id?	새 문서 추가	1 API call
update_document	doc_id, content \| title	기존 문서 편집	1 API call
add_database_row	database_id, fields: obj	구조화된 데이터 입력	1 API call

비용 및 제한

운영 비용

API 쿼터: AFFiNE 플랜 한도
호출당 토큰: 문서 내용은 편차가 큽니다 — 가능하면 섹션 단위로 자르세요
금액: AFFiNE 셀프 호스팅은 무료; Cloud는 유료 플랜 존재
팁: 목록 조회 후 코드에서 필터링하기보다 search_documents를 쓰세요.

보안

권한, 시크릿, 파급범위

최소 스코프: 가능하면 워크스페이스 범위로 제한된 API 토큰

자격 증명 저장: AFFINE_API_TOKEN 환경 변수; 절대 커밋하지 마세요

데이터 외부 송신: AFFiNE 데이터가 LLM 제공자에게 전송됨

절대 부여 금지: 공용 머신에서의 쿠키 인증 — 쿠키는 사용자 세션과 동일

브라우저 로컬 전용 워크스페이스는 MCP에서 보이지 않습니다 — 서버 기반 워크스페이스만 동작합니다.
AFFiNE Cloud에서는 프로그램적 로그인에 대해 Cloudflare가 이메일/비밀번호를 차단합니다 — API 토큰을 쓰세요.

문제 해결

자주 발생하는 오류와 해결

401 / token invalid

Settings > Integrations > MCP Server에서 재발급하세요. 새 토큰을 env에 붙여넣으세요.

Cannot find workspace

서버 기반 vs 로컬 전용 혼동입니다. 서버 기반 워크스페이스만 접근 가능합니다.

확인: AFFiNE UI를 여세요; 워크스페이스가 클라우드 동기화되어 있나요?

DB row rejected — field type mismatch

먼저 스키마를 확인하고 타입을 맞추세요. 날짜는 ISO-8601 문자열이 필요한 경우가 많습니다.

대안

affine-mcp-server 다른 것과 비교

대안	언제 쓰나	단점/장점
Notion MCP	AFFiNE 대신 Notion을 쓸 때	다른 제품; 생태계가 더 성숙
Obsidian MCP	Obsidian 마크다운 파일에 올인했을 때	로컬 우선; 다른 철학

affine-mcp-server