위키독스 MCP 서버
AI 에이전트가 위키독스(Wikidocs) 책과 블로그를 읽고, 편집하고, 관리할 수 있도록 하는 Model Context Protocol (MCP) 서버입니다.
✨ 주요 기능
📚 책 관리
- 스마트 캐싱: 대량 페이지 데이터를 로컬에 캐시하여 성능 최적화
- 키워드 검색: 책 내용에서 관련도 기반 페이지 검색
- 구조 탐색: 책의 목차 구조를 요약하여 전체 구조 파악
- 페이지 CRUD: 페이지 읽기, 생성, 수정 기능
📝 블로그 관리
- 블로그 포스트 목록 조회 및 내용 읽기
- 새 포스트 생성 및 기존 포스트 수정
- 태그 관리 및 공개/비공개 설정
🖼️ 이미지 업로드
- 페이지 및 블로그용 이미지 업로드 지원
🚀 빠른 시작
1. 설치
git clone https://github.com/ychoi-kr/wikidocs-mcp.git
cd wikidocs-mcp
pip install -r requirements.txt
2. 환경 설정
.env 파일을 생성하고 위키독스 API 토큰을 설정합니다.
WIKIDOCS_API_TOKEN="여기에_발급받은_API_토큰을_입력하세요"
💡 API 토큰 발급: 위키독스 로그인 > 계정설정 > API 토큰에서 토큰을 확인할 수 있습니다.
3. Claude Desktop 연결
Claude Desktop 설정 파일(claude_desktop_config.json)에 서버를 등록합니다:
{
"mcpServers": {
"wikidocs": {
"command": "/opt/anaconda3/bin/python3",
"args": ["/Users/your-username/wikidocs-mcp/main.py"]
}
}
}
⚠️ 중요: 경로를 본인 환경에 맞게 수정하세요.
- Python 경로 확인:
which python3- 프로젝트 경로 확인:
pwd
4. 테스트 실행
Claude Desktop을 재시작하고 다음과 같이 테스트해 보세요.
내 책 목록을 보여줘
MCP 클라이언트가 인자 없이 툴을 호출하는 문제를 진단하려면 CLI에서 직접 다음을 실행해 보세요.
claude mcp call wikidocs-mcp get_book_structure --json '{"book_id": 12345, "max_depth": 3}'
🛠️ 도구 목록
📖 책 관리 도구
| 도구명 | 설명 | 사용 예시 |
|---|---|---|
list_my_books | 내가 작성한 책 목록 조회 | "내 책 목록을 보여줘" |
get_book_info | 책 정보 조회 및 캐시 저장 | "책 ID 123의 정보를 가져와줘" |
search_book_pages | 키워드로 페이지 검색 | "MCP 관련 내용을 찾아줘" |
get_book_structure | 책 목차 구조 요약 | "이 책의 구조를 보여줘" |
get_page | 특정 페이지 내용 조회 | "페이지 456의 내용을 보여줘" |
create_page | 새 페이지 생성 | "새로운 챕터를 추가해줘" |
update_page | 페이지 내용 수정 | "이 페이지를 수정해줘" |
renumber_pages | 페이지 번호 일괄 변경 | "5.2절부터 번호를 하나씩 뒤로 밀어줘" |
upload_page_image | 페이지용 이미지 업로드 | "이미지를 업로드해줘" |
get_cache_status | 캐시 상태 확인 | "캐시 상태를 확인해줘" |
📝 블로그 관리 도구
| 도구명 | 설명 | 사용 예시 |
|---|---|---|
get_blog_profile | 블로그 프로필 정보 조회 | "내 블로그 정보를 보여줘" |
get_blog_list | 블로그 포스트 목록 조회 | "최근 블로그 포스트를 보여줘" |
get_blog_post | 특정 포스트 내용 조회 | "포스트 789의 내용을 보여줘" |
create_blog_post | 새 포스트 생성 | "새 블로그 포스트를 작성해줘" |
update_blog_post | 포스트 내용 수정 | "이 포스트를 수정해줘" |
upload_blog_image | 블로그용 이미지 업로드 | "블로그 이미지를 업로드해줘" |
💡 사용법 예시
기본 워크플로
1. 책 목록 확인
→ "내 위키독스 책 목록을 보여줘"
2. 특정 책 로드
→ "책 ID 99999의 정보를 가져와줘"
(대량 페이지 데이터가 로컬 캐시에 저장됨)
3. 키워드 검색
→ "MCP 관련 내용을 검색해줘"
(관련도 높은 페이지들만 반환)
4. 상세 내용 조회
→ "페이지 99999999의 전체 내용을 보여줘"
5. 내용 수정
→ "이 페이지에 새로운 예제를 추가해줘"
고급 활용 예시
# 책 전체 분석
"MCP 가이드 책의 구조를 분석하고, 부족한 부분이 있으면 알려줘"
# 콘텐츠 최적화
"이 책에서 'MCP'라는 키워드가 나오는 모든 페이지를 찾아서 설명의 일관성을 확인해줘"
# 자동 블로그 포스팅
"책의 3장 내용을 요약해서 블로그 포스트로 작성해줘"
🏗️ 아키텍처
프로젝트 구조
wikidocs-mcp/
├── main.py # 메인 서버 진입점
├── book_tools.py # 책 관련 도구들
├── blog_tools.py # 블로그 관련 도구들
├── utils.py # 공통 유틸리티 함수
├── search_utils.py # 캐시 및 검색 기능
├── .env # 환경 변수 (API 토큰)
└── requirements.txt # 패키지 의존성
캐시 시스템
- 위치:
~/.wikidocs_mcp_cache/ - 구조:
book_{id}.json: 책 데이터book_{id}_meta.json: 캐시 메타데이터
- 유효기간: 24시간 (설정 가능)
- 자동 무효화: 페이지 생성/수정 시
검색 알고리듬
- 텍스트 정규화: HTML 태그 제거, 특수문자 처리
- 관련도 점수 계산:
- 제목 매칭: 10.0점 (완전 일치 시 +5.0점)
- 내용 매칭: 매칭 수 × 2.0점
- 부분 매칭: 단어별 0.5-3.0점
- 결과 정렬: 관련도 점수 기준 내림차순
📚 참고 자료
- 위키독스 API 문서
- Model Context Protocol
- MCP: AI 에이전트 시대의 통합 가이드 (이 프로젝트의 기반이 된 책)
🛡️ 보안 및 주의사항
- API 토큰 보안:
.env파일을 절대 git에 커밋하지 마세요 - 권한 확인: MCP 도구 실행 시 Claude가 권한을 요청합니다
- 캐시 관리: 민감한 정보가 포함된 경우 캐시 디렉터리를 주기적으로 정리하세요
📄 라이선스
MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.
🤝 기여하기
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📞 지원 및 문의
- Issues: GitHub Issues