위키독스 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시간 (설정 가능)
• 자동 무효화: 페이지 생성/수정 시

검색 알고리듬

1. 텍스트 정규화: HTML 태그 제거, 특수문자 처리
2. 관련도 점수 계산:
   • 제목 매칭: 10.0점 (완전 일치 시 +5.0점)
   • 내용 매칭: 매칭 수 × 2.0점
   • 부분 매칭: 단어별 0.5-3.0점
3. 결과 정렬: 관련도 점수 기준 내림차순

📚 참고 자료

• 위키독스 API 문서
• Model Context Protocol
• MCP: AI 에이전트 시대의 통합 가이드 (이 프로젝트의 기반이 된 책)

🛡️ 보안 및 주의사항

• API 토큰 보안: .env 파일을 절대 git에 커밋하지 마세요
• 권한 확인: MCP 도구 실행 시 Claude가 권한을 요청합니다
• 캐시 관리: 민감한 정보가 포함된 경우 캐시 디렉터리를 주기적으로 정리하세요

📄 라이선스

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.

🤝 기여하기

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 지원 및 문의

• Issues: GitHub Issues