BookStack MCP 서버

AI 어시스턴트가 BookStack 문서에 완전히 액세스하여 콘텐츠를 검색, 읽기, 생성 및 관리할 수 있도록 하는 Model Context Protocol (MCP) 서버입니다.

npx bookstack-mcp

기능

• 20개의 읽기 전용 도구 + 18개의 쓰기 도구로 완벽한 BookStack API 커버리지 제공

• 책, 챕터, 페이지, 선반, 첨부 파일 및 댓글에 대한 전체 CRUD 지원

• 휴지통 지원 — 소프트 삭제된 콘텐츠 복원 또는 영구 삭제

• Zod를 사용한 타입 안전 입력 검증 (광범위한 클라이언트 호환성을 위해 문자열/숫자 매개변수 자동 변환)

• 모든 응답에 포함된 URL 및 콘텐츠 미리보기

• HTML로 작성된 페이지를 위한 마크다운 내보내기 대체 기능으로 AI 클라이언트가 항상 사용 가능한 콘텐츠를 확보

• 안전을 위해 쓰기 작업은 기본적으로 비활성화됨

• Claude Desktop, Claude Code, LibreChat 및 모든 MCP 호환 클라이언트와 작동

• Stdio 및 Streamable HTTP 전송 지원

Related MCP server: PDF RAG MCP Server

빠른 시작

npm에서 설치

npx bookstack-mcp

또는 복제 및 빌드

git clone https://github.com/ttpears/bookstack-mcp.git
cd bookstack-mcp
npm install && npm run build
npm start

환경 변수

BOOKSTACK_BASE_URL=https://your-bookstack.com   # Required
BOOKSTACK_TOKEN_ID=your-token-id                # Required
BOOKSTACK_TOKEN_SECRET=your-token-secret        # Required
BOOKSTACK_ENABLE_WRITE=false                    # Optional, default false
BOOKSTACK_INSECURE_SKIP_TLS_VERIFY=false        # Optional, default false

보안 경고: BOOKSTACK_INSECURE_SKIP_TLS_VERIFY=true는 BookStack으로 나가는 요청에 대한 TLS 인증서 검증을 비활성화합니다. 신뢰할 수 있는 LAN 내의 자체 서명 인증서에만 사용하십시오. 연결이 MITM 공격에 취약해질 수 있습니다. 이 옵션이 활성화될 때마다 서버는 시작 시 WARNING 로그를 출력합니다.

클라이언트 구성

Claude Desktop

Claude Desktop 설정에 추가:

{
  "mcpServers": {
    "bookstack": {
      "command": "npx",
      "args": ["-y", "bookstack-mcp"],
      "env": {
        "BOOKSTACK_BASE_URL": "https://your-bookstack.com",
        "BOOKSTACK_TOKEN_ID": "your-token-id",
        "BOOKSTACK_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

LibreChat (stdio, 단일 사용자)

librechat.yaml에 추가:

mcpServers:
  bookstack:
    command: npx
    args:
      - -y
      - bookstack-mcp
    env:
      BOOKSTACK_BASE_URL: "https://your-bookstack.com"
      BOOKSTACK_TOKEN_ID: "your-token-id"
      BOOKSTACK_TOKEN_SECRET: "your-token-secret"

LibreChat (Streamable HTTP, 프로덕션/Docker 권장)

서버를 장기 실행 HTTP 서비스로 실행하고 LibreChat이 해당 URL을 가리키도록 합니다. 이는 다중 사용자 또는 컨테이너화된 배포에 적합한 설정입니다.

HTTP 모드로 서버 시작:

MCP_TRANSPORT=http \
MCP_HTTP_PORT=8080 \
BOOKSTACK_BASE_URL=https://your-bookstack.com \
BOOKSTACK_TOKEN_ID=your-token-id \
BOOKSTACK_TOKEN_SECRET=your-token-secret \
npx bookstack-mcp

그런 다음 LibreChat 구성:

mcpServers:
  bookstack:
    type: streamable-http
    url: http://bookstack-mcp:8080/mcp

3.0.0 주요 변경 사항: 더 이상 사용되지 않는 HTTP+SSE 전송(GET /sse + POST /messages)이 제거되었습니다. /mcp의 Streamable HTTP는 이미 스트리밍 응답을 위해 SSE를 사용하며, 현재 MCP 클라이언트에서 유일한 HTTP 전송 방식입니다. 레거시 엔드포인트가 필요한 이전 클라이언트를 사용하는 경우 bookstack-mcp@2.x 버전을 고정하십시오.

HTTP 전송 환경 변수

0.0.0.0에 바인딩할 때(예: 다른 서비스에서 접근 가능한 컨테이너 내부), MCP_HTTP_ALLOWED_HOSTS를 LibreChat이 이 서버에 도달하기 위해 사용할 호스트 이름(예: MCP_HTTP_ALLOWED_HOSTS=bookstack-mcp,bookstack-mcp.internal)으로 설정하십시오.

구성 변경 후 LibreChat을 다시 시작하십시오.

Claude Code (CLI)

권장 경로는 이 저장소의 플러그인 매니페스트(.claude-plugin/plugin.json)를 제공하는 ttpears/claude-plugins 마켓플레이스입니다:

/plugin marketplace add ttpears/claude-plugins
/plugin install bookstack-mcp@ttpears-plugins

그런 다음 셸에서 BOOKSTACK_* 환경 변수를 설정하여 플러그인의 MCP 서버가 인증할 수 있도록 하십시오:

export BOOKSTACK_BASE_URL=https://your-bookstack.com
export BOOKSTACK_TOKEN_ID=your-token-id
export BOOKSTACK_TOKEN_SECRET=your-token-secret

수동 설치 (대안)

마켓플레이스를 사용하지 않으려면 claude mcp add를 사용하여 서버를 직접 등록하십시오. 각 변수에 대해 --env를 반복하고, 모든 플래그를 서버 이름 앞에 배치하며, --를 사용하여 Claude Code가 실행할 명령의 시작을 표시하십시오:

claude mcp add bookstack \
  --transport stdio \
  --scope user \
  --env BOOKSTACK_BASE_URL=https://your-bookstack.com \
  --env BOOKSTACK_TOKEN_ID=your-token-id \
  --env BOOKSTACK_TOKEN_SECRET=your-token-secret \
  -- npx -y bookstack-mcp

범위(Scope)는 항목이 기록되는 위치를 결정합니다:

결과 구성 항목은 다음과 같습니다 (프로젝트 범위의 경우 .mcp.json, 그 외에는 ~/.claude.json):

{
  "mcpServers": {
    "bookstack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "bookstack-mcp"],
      "env": {
        "BOOKSTACK_BASE_URL": "https://your-bookstack.com",
        "BOOKSTACK_TOKEN_ID": "your-token-id",
        "BOOKSTACK_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

커밋된 .mcp.json을 위한 팁: Claude Code는 .mcp.json 내의 ${VAR} 및 ${VAR:-default} 참조를 주변 셸에서 확장합니다. 이를 사용하여 비밀 정보를 git에서 제외하십시오: 파일에 "BOOKSTACK_TOKEN_SECRET": "${BOOKSTACK_TOKEN_SECRET}"을 설정하고 각 개발자가 셸에서 변수를 내보내도록 하십시오.

MCP 리소스

책과 페이지는 MCP 리소스로도 노출되므로 리소스를 탐색하는 클라이언트(Claude Desktop, MCP Inspector 등)는 직접 @-멘션할 수 있습니다:

두 템플릿 모두 id 자동 완성을 지원합니다: 입력하는 동안 서버가 BookStack을 검색하여 일치하는 ID를 반환하므로 숫자 ID를 직접 기억할 필요가 없습니다.

사용 가능한 도구

읽기 작업 (항상 사용 가능)

쓰기 작업 (BOOKSTACK_ENABLE_WRITE=true 필요)

BookStack API 설정

1. 관리자로 BookStack에 로그인

2. 설정 > 사용자 > 사용자 편집으로 이동

3. 사용자가 시스템 API 액세스 권한을 가지고 있는지 확인

4. API 토큰 섹션에서 새 토큰 생성

5. 토큰 ID와 토큰 시크릿 복사

보안

• 쓰기 작업은 기본적으로 비활성화됨

• 프로덕션 인스턴스에는 HTTPS 사용

• API 토큰을 안전하게 저장 (git에 절대 커밋하지 마십시오)

• 제한된 권한을 가진 전용 BookStack 사용자 고려

개발

npm run dev          # Hot reload with tsx
npm run type-check   # Type checking only
npm run build        # Production build

라이선스

MIT