docmost-mcp

AI 에이전트가 자체 호스팅 Docmost 위키에 일반 REST API를 통해 읽기/쓰기 접근할 수 있게 해주는 MCP 서버입니다.

왜 필요한가

Docmost는 자체 MCP 엔드포인트를 제공하지만 유료 라이선스 뒤에 있습니다. Settings UI에서 API 관리는 *"Available with a paid license"*로 표시되며, Community Edition에서는 /api/mcp가 404를 반환합니다. API 키 발급도 동일하게 제한됩니다.

하지만 일반 REST API는 Community Edition에서 완전히 열려 있습니다. 이 서버는 그 위에 얇은 래퍼입니다: 동일한 작업, API 키 대신 세션 인증을 사용합니다.

Related MCP server: wikidocs-mcp

요구 사항

• Python 3.11+

• HTTP(S)로 접근 가능한 Docmost 인스턴스

• 에이전트 전용 Docmost 사용자 계정

설치

git clone https://github.com/<you>/docmost-mcp.git
cd docmost-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

구성

예제 설정 파일을 복사하여 작성하세요:

cp config.example.json config.json
chmod 600 config.json

{
  "url": "https://docmost.example.com",
  "api_key": "",
  "email": "agent@example.com",
  "password": "..."
}

두 가지 인증 모드를 지원합니다:

api_key가 설정되면 우선 적용되고, 그렇지 않으면 자격 증명이 사용됩니다.

설정 파일 경로는 DOCMOST_MCP_CONFIG 환경 변수로 재정의할 수 있습니다.

전용 계정 만들기

워크스페이스 소유자의 자격 증명을 사용하지 마세요. 별도의 사용자를 초대하고(Settings → Members → Invite) 에이전트가 필요한 공간에만 접근 권한을 부여하세요. Docmost의 공간 접근은 일반적으로 기본 Everyone 그룹에서 상속되므로, 에이전트가 제한되어 있다고 가정하기 전에 해당 그룹이 접근할 수 있는 범위를 확인하세요.

Gmail 스타일의 플러스 주소(you+agent@gmail.com)는 두 번째 사서함을 만들고 싶지 않을 때 사용할 수 있습니다.

검증

selftest.py는 로그인, 읽기, 쓰기, 다시 읽기, 삭제의 전체 체인을 테스트합니다:

./venv/bin/python selftest.py

에이전트 연결

이 서버는 stdio를 통해 MCP를 사용합니다.

Claude Code

claude mcp add docmost -- /path/to/docmost-mcp/venv/bin/python /path/to/docmost-mcp/server.py

또는 ~/.claude.json에 수동으로 추가하세요:

{
  "mcpServers": {
    "docmost": {
      "type": "stdio",
      "command": "/path/to/docmost-mcp/venv/bin/python",
      "args": ["/path/to/docmost-mcp/server.py"],
      "env": {}
    }
  }
}

이후 Claude Code를 다시 시작하세요 — 설정은 시작 시 읽힙니다.

Claude Desktop

claude_desktop_config.json에 동일한 블록을 추가하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor

프로젝트의 .cursor/mcp.json에 추가하거나 전역적으로 ~/.cursor/mcp.json에 추가하세요. 동일한 mcpServers 형태를 사용합니다.

기타 MCP 클라이언트

virtualenv의 Python으로 server.py를 실행하고 stdin/stdout을 통해 JSON-RPC를 사용하세요. 최소한의 핸드셰이크:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}

편의 래퍼를 사용하면 명령을 짧게 유지할 수 있습니다:

#!/bin/sh
exec /path/to/docmost-mcp/venv/bin/python /path/to/docmost-mcp/server.py "$@"

도구

fmt는 markdown(기본값), html 또는 json입니다.

Docmost API 참고 사항

이 서버를 확장할 때 알아두면 좋은 점:

• 모든 엔드포인트는 읽기 포함 POST입니다.

• /pages/create 및 /pages/update는 반드시 format 필드(json | markdown | html)가 필요합니다. 생략하면 400을 반환합니다.

• 응답은 페이로드를 {"data": ...}로 감쌉니다. 클라이언트가 이를 풉니다.

• /api/api-keys는 Community Edition에서 빈 목록과 함께 200을 반환합니다 — 목록 조회는 열려 있지만 키 생성만 라이선스로 제한됩니다.

• 엔드포인트 경로와 페이로드 형태는 Docmost 클라이언트 소스(apps/client/src/features/*/services/*.ts)에서 가져온 것이지 추측한 것이 아닙니다.

보안

• config.json에는 평문 비밀번호가 저장됩니다. 모드를 600으로 유지하고 버전 관리에서 제외하세요 — .gitignore에 포함되어 있습니다.

• 에이전트 계정에 작업에 필요한 최소한의 공간 접근 권한만 부여하세요.

• 계정의 작업은 Docmost에서 자신의 이름으로 표시되므로 페이지 기록이 추적 가능합니다.

호환성

Docmost 0.95.0 및 Python MCP SDK 2.0을 기준으로 빌드되었습니다. SDK 2.0은 FastMCP를 MCPServer로 이름을 바꾸고 mcp.server로 이동했습니다. 2.0 이전의 mcp.server.fastmcp 임포트 경로는 작동하지 않습니다.

라이선스

MIT — LICENSE 참조.

이 프로젝트는 Docmost와 제휴 관계가 없습니다.