Wiki.js 인스턴스를 AI 에이전트의 지식 베이스처럼 사용할 수 있게 해주는 MCP(Model Context Protocol) 서버.
AI 에이전트가 위키 페이지를 검색, 조회, 생성, 수정, 삭제할 수 있도록 Wiki.js GraphQL API를 브릿지한다.
이 글은 원래 필요한 사람들에게 도움을 주기 위해 Wiki.js 공식 Discussions에 게시했으나, 알 수 없는 이유로 글이 삭제되어 이곳에 다시 작성한다.
requarks-wiki-mcp는 Claude Code나 Claude Desktop 같은 MCP 클라이언트에서 Wiki.js를 지식 베이스로 활용할 수 있도록 설계된 MCP 서버다.
| 항목 | 값 |
|---|---|
| 패키지명 | @yowu-dev/requarks-wiki-mcp |
| 버전 | v0.3.1 |
| 라이선스 | MIT |
| Node.js | 20+ |
| 전송 방식 | stdio (stdin/stdout) |
| GitHub | uyu423/requarks-wiki-mcp |
| npm | @yowu-dev/requarks-wiki-mcp |
requarks-wiki-mcp/
├── src/
│ ├── index.ts # 부트스트랩: config → ctx → 도구 등록 → 연결
│ ├── types.ts # 공유 타입: WikiConfig, ToolContext, ToolModule
│ ├── config.ts # 환경변수 파싱: loadConfig() → WikiConfig
│ ├── errors.ts # 에러 분류 체계 (WikiError 계층) + LLM 포맷팅
│ ├── graphql.ts # GraphQL 클라이언트 팩토리 (타임아웃 + 재시도)
│ ├── safety.ts # 쓰기 안전장치 + 경로 정규화 + 감사 로깅
│ ├── resources/ # MCP 리소스 (마크다운 가이드, Mermaid 가이드, 권한 가이드)
│ └── tools/ # 도구별 1파일 (29개)
│ ├── registry.ts # allTools[] 내보내기 (단일 임포트)
│ ├── searchPages.ts # wikijs_search_pages
│ ├── createPage.ts # wikijs_create_page (mutation)
│ └── ... # 나머지 27개 도구
├── test/ # node:test 기반 테스트
├── dist/ # 빌드 출력
└── package.json # ESM, Node >=20
Administration → API로 이동Claude Code에서 사용하려면 ~/.claude.json의 mcpServers 필드에 추가한다.
Claude Code는
~/.claude.json파일에서 MCP 서버를 로드한다.~/.claude/.mcp.json이나settings.json의mcpServers는 무시된다.
{
"mcpServers": {
"wikijs": {
"command": "npx",
"args": ["-y", "@yowu-dev/requarks-wiki-mcp@latest"],
"env": {
"WIKI_BASE_URL": "https://wiki.your-domain.dev",
"WIKI_API_TOKEN": "your_wikijs_api_key_jwt",
"WIKI_GRAPHQL_PATH": "/graphql",
"WIKI_DEFAULT_LOCALE": "ko",
"WIKI_DEFAULT_EDITOR": "markdown",
"WIKI_MUTATIONS_ENABLED": "true",
"WIKI_MUTATION_CONFIRM_TOKEN": "",
"WIKI_MUTATION_DRY_RUN": "false",
"WIKI_ALLOWED_MUTATION_PATH_PREFIXES": "",
"WIKI_HTTP_TIMEOUT_MS": "15000",
"WIKI_HTTP_MAX_RETRIES": "2"
}
}
}
}
npm 배포 없이 로컬에서 직접 실행할 수도 있다.
git clone https://github.com/uyu423/requarks-wiki-mcp.git
cd requarks-wiki-mcp
npm install && npm run build
{
"mcpServers": {
"wikijs": {
"command": "node",
"args": ["/absolute/path/to/requarks-wiki-mcp/dist/index.js"],
"env": {
"WIKI_BASE_URL": "https://wiki.your-domain.dev",
"WIKI_API_TOKEN": "your_wikijs_api_key_jwt",
"WIKI_MUTATIONS_ENABLED": "true"
}
}
}
}
| 변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
WIKI_BASE_URL |
O | - | Wiki.js 기본 URL |
WIKI_API_TOKEN |
O | - | Wiki.js API 키 JWT |
WIKI_GRAPHQL_PATH |
X | /graphql |
GraphQL 엔드포인트 경로 |
WIKI_DEFAULT_LOCALE |
X | en |
기본 locale |
WIKI_DEFAULT_EDITOR |
X | markdown |
기본 에디터 |
WIKI_MUTATIONS_ENABLED |
X | false |
쓰기 도구 활성화 여부 |
WIKI_MUTATION_CONFIRM_TOKEN |
X | (빈값) | 쓰기 추가 안전장치 토큰 |
WIKI_MUTATION_DRY_RUN |
X | true |
드라이런 모드 (미리보기만) |
WIKI_ALLOWED_MUTATION_PATH_PREFIXES |
X | (빈값) | 쓰기 허용 경로 prefix (쉼표 구분) |
WIKI_HTTP_TIMEOUT_MS |
X | 15000 |
HTTP 타임아웃 (ms) |
WIKI_HTTP_MAX_RETRIES |
X | 2 |
읽기 실패 최대 재시도 횟수 |
| 도구 | 설명 |
|---|---|
wikijs_search_pages |
위키 페이지 전체 텍스트 검색 |
wikijs_list_pages |
locale 필터 및 정렬로 페이지 목록 조회 |
wikijs_get_page_by_path |
경로 + locale로 페이지 본문 조회 |
wikijs_get_page_by_id |
숫자 ID로 페이지 본문 조회 |
wikijs_get_page_tree |
사이트 계층 탐색 (폴더/페이지/전체) |
wikijs_get_page_history |
페이지 편집 히스토리 조회 |
wikijs_get_page_version |
특정 버전의 전체 본문 조회 |
wikijs_get_page_links |
페이지 링크 관계 (지식 그래프) |
| 도구 | 설명 |
|---|---|
wikijs_list_tags |
모든 태그 목록 조회 |
wikijs_search_tags |
쿼리와 일치하는 태그 검색 |
| 도구 | 설명 |
|---|---|
wikijs_list_comments |
페이지의 모든 댓글 목록 조회 |
wikijs_get_comment |
ID로 단일 댓글 조회 |
| 도구 | 설명 |
|---|---|
wikijs_get_system_info |
Wiki.js 버전, DB 유형, 사용 통계 |
wikijs_get_navigation |
네비게이션 트리 구조 |
wikijs_get_site_config |
사이트 설정 (민감 정보 제외) |
wikijs_list_assets |
에셋 목록 조회 |
wikijs_list_asset_folders |
에셋 폴더 목록 조회 |
wikijs_get_current_user |
현재 인증된 사용자 프로필 |
wikijs_search_users |
사용자 검색 |
쓰기 도구는
WIKI_MUTATIONS_ENABLED=true일 때만 활성화된다.
| 도구 | 설명 |
|---|---|
wikijs_create_page |
새 페이지 생성 (본문, 태그, 메타데이터) |
wikijs_update_page |
기존 페이지 수정 |
wikijs_delete_page |
페이지 삭제 |
wikijs_move_page |
페이지 이동/이름 변경 |
wikijs_restore_page |
이전 버전으로 복원 |
| 도구 | 설명 |
|---|---|
wikijs_create_comment |
페이지에 댓글 생성 |
wikijs_update_comment |
댓글 수정 |
wikijs_delete_comment |
댓글 삭제 |
| 도구 | 설명 |
|---|---|
wikijs_update_tag |
태그의 slug/title 수정 |
wikijs_delete_tag |
모든 페이지에서 태그 삭제 |
이 MCP 서버는 의도하지 않은 쓰기를 방지하기 위해 4단계 안전장치를 제공한다.
WIKI_MUTATIONS_ENABLED가 기본적으로 false이므로, 명시적으로 활성화하지 않으면 모든 쓰기 도구가 차단된다.
WIKI_MUTATION_CONFIRM_TOKEN을 설정하면, 모든 쓰기 호출에 일치하는 confirm 값이 필요하다. timing-safe 비교를 사용하여 타이밍 공격을 방지한다.
WIKI_ALLOWED_MUTATION_PATH_PREFIXES로 쓰기를 허용할 경로를 제한할 수 있다. 예: dev,tips로 설정하면 dev/ 및 tips/ 하위에서만 쓰기가 가능하다.
WIKI_MUTATION_DRY_RUN=true(기본값)이면 실제 쓰기 대신 미리보기만 반환한다.
모든 쓰기 시도(드라이런 포함)는 구조화된 JSON으로 stderr에 기록된다. 민감 정보(API 토큰 등)는 자동으로 [REDACTED] 처리된다.
LLM이 에러를 이해하고 스스로 해결할 수 있도록 타입 기반 에러 분류와 수정 안내를 제공한다.
| 에러 클래스 | 코드 | 설명 |
|---|---|---|
WikiAuthError |
401 | API 토큰 인증 실패 |
WikiForbiddenError |
403 | 권한 부족 (6008~6013) |
WikiNotFoundError |
404 | 페이지/댓글 없음 |
WikiValidationError |
422 | 입력값 검증 실패 |
WikiTransientError |
5xx | 일시적 서버 오류 |
WikiRateLimitedError |
429 | 요청 제한 초과 |
WikiMutationDisabledError |
- | 쓰기 비활성화 상태 |
WikiInvalidTokenError |
- | 확인 토큰 불일치 |
WikiPathNotAllowedError |
- | 허용되지 않은 경로 |
| 코드 | 의미 | 해결 방법 |
|---|---|---|
| 6002 | PageDuplicateCreate |
이미 같은 경로에 페이지 존재 |
| 6003 | PageNotFound |
페이지 경로/ID 확인 |
| 6004 | PageEmptyContent |
본문 내용 필수 |
| 6005 | PageIllegalPath |
경로에 유효하지 않은 문자 포함 |
| 6013 | PageViewForbidden |
read:pages/read:source 권한 확인 |
| 8002 | CommentPostForbidden |
write:comments 권한 확인 |
read:pages, read:sourceread:commentsread:pages, read:source, write:pagesmanage:pages 또는 delete:pages (삭제/이동용)read:comments, write:comments, manage:commentsmanage:system (태그 관리용)이 서버는 3개의 내장 리소스를 제공한다. LLM이 이 리소스를 읽어 Wiki.js 마크다운 문법이나 다이어그램 작성, 권한 문제를 스스로 해결할 수 있다.
| 리소스 URI | 설명 |
|---|---|
wikijs://markdown-guide |
Wiki.js 마크다운 문법 가이드 (CommonMark/GFM + 확장) |
wikijs://mermaid-guide |
Wiki.js 번들 Mermaid 8.8.2 다이어그램 문법 가이드 (지원 9종 다이어그램, 미지원 기능 경고, 버전 제한사항) |
wikijs://api-permissions-guide |
API 권한 모델, 에러 코드, 자가 진단 가이드 |
이 MCP 서버를 더 효과적으로 활용하려면, 본인 환경에 맞는 별도의 Claude Code Skill을 만들어서 사용하는 것을 권장한다.
Skill을 통해 위키 구조, 경로 규칙, 콘텐츠 스타일 가이드, 관련 문서 자동 연결 등을 시스템 프롬프트로 정의하면 AI 에이전트가 위키를 훨씬 더 체계적으로 관리할 수 있다.
Skill 샘플은 이 Gist에서 확인할 수 있다.
~/.claude/skills/wiki-knowledge-manager/
├── skill.md # Skill 정의 (시스템 프롬프트)
└── ...
/dev/**, /tips/**, /notes/**, /book/** 등 경로별 용도API 토큰은 서버 측에만 보관하고, 클라이언트에 노출하지 않는다.
WIKI_MUTATIONS_ENABLED=false 유지WIKI_MUTATION_DRY_RUN=true로 테스트WIKI_MUTATION_CONFIRM_TOKEN에 강력한 랜덤 토큰 사용WIKI_ALLOWED_MUTATION_PATH_PREFIXES로 쓰기 범위 최소화wikijs_get_system_info는 dbHost, configFile 등을 자동으로 제외scriptJs/scriptCss 필드는 10,000자로 제한Wiki.js GraphQL API를 사용할 때 주의할 점:
pages.tree의 mode는 GraphQL enum (FOLDERS, PAGES, ALL)으로 전달해야 한다pages.history는 offsetPage/offsetSize로 페이지네이션한다 (offset/limit 아님)locale 필드는 null을 반환하므로 응답에서 요청하면 안 된다update 시 tags가 undefined이면 Wiki.js가 .map() 에러로 충돌한다 (항상 [] 전달)update 시 description이 null이면 거부된다 (undefined 또는 문자열 사용)