Slima MCP

Claude / ChatGPT / Cursor / Gemini에서 Slima 책 읽기와 쓰기

MCP 첫 설정

• 01 Slima MCP란? MCP(Model Context Protocol)는 AI 도구가 외부 시스템을 읽고 쓰기 위한 표준입니다. Slima MCP는 Claude / ChatGPT / Cursor / Gemini가 Slima 작품을 직접 읽고 쓸 수 있게 해줍니다.
• 02 Slima MCP vs file MCP vs 내장 AI 코치 AI가 글에 접근하는 3가지 경로 — Slima MCP (API로 작품 직접 연결), file MCP (로컬 폴더 지정), 그리고 에디터 안의 AI 코치.
• 03 연결 방식 선택하기: Web vs 로컬 Slima MCP 두 가지 연결 경로: Web (OAuth, claude.ai / ChatGPT용) vs 로컬 stdio (npm 패키지 설치, Claude Desktop / Cursor / Gemini CLI용).

웹 연결 (OAuth)

• 01 claude.ai에서 Slima 연결하기 (권장) claude.ai에 Slima MCP를 커스텀 커넥터로 추가합니다. OAuth 절차와 필요한 Claude 플랜(Pro / Max / Team / Enterprise)을 안내합니다.
• 02 ChatGPT에서 Slima 연동하기 ChatGPT에서 Slima MCP를 쓰려면 Developer Mode(2025.10+) + Custom MCP Server + OAuth가 필요합니다. ChatGPT Plus / Pro 플랜에서만 사용 가능합니다.

로컬 연결 (stdio)

• 01 Claude Desktop 연결하기 Claude Desktop에서 Slima MCP 로컬 연결: claude_desktop_config.json 편집 + npx slima-mcp@0 + 토큰 환경변수. Mac / Windows 경로 안내.
• 02 Cursor 연결하기 Cursor에 Slima MCP 추가하기: Settings → MCP → 서버 추가 + npx slima-mcp@0 실행. Claude Desktop과 비슷하지만 UI가 다릅니다.
• 03 Gemini CLI 연결 Gemini CLI에 Slima MCP 추가: gemini mcp add slima --command "npx -y slima-mcp@0". Gemini CLI 0.4 이상 필요.
• 04 VS Code 연결 VS Code는 MCP 확장을 통해 연결합니다. 자주 쓰는 확장: MCP Tools / Continue.

토큰 관리

• 01 SLIMA_API_TOKEN 받기 두 가지 방법이 있습니다: npx slima-mcp@0 auth로 브라우저 로그인 후 ~/.slima/credentials.json에 저장하거나, 브라우저가 없는 서버 / CI 환경에서 SLIMA_API_TOKEN을 직접 설정하는 방법입니다.
• 02 slima-mcp CLI 커맨드 레퍼런스 `slima-mcp` CLI의 모든 커맨드: auth / status / logout / --help / --version. 각 커맨드의 설명과 예시를 정리했습니다.
• 03 승인된 앱 관리 계정 → API 토큰 / 승인된 앱: 무엇이 연결되어 있는지, 마지막 사용 시각을 확인하고 개별 또는 일괄로 해지하십시오.

버전과 업그레이드

• 01 `slima-mcp@0`을 쓰는 이유: 버전 고정 전략 모든 예시에서 `slima-mcp`가 아니라 `slima-mcp@0`을 씁니다. `@0`은 메이저 버전 고정입니다. 0.x의 패치와 마이너 업데이트는 자동으로 받고, 1.0의 호환성 깨는 변경은 직접 결정해서 넘어갑니다.
• 02 전역 설치에서 `npx` 방식으로 옮기기 예전에는 `npm install -g slima-mcp`을 사용했지만, 새 방식은 `npx -y slima-mcp@0`입니다. 왜 옮겨야 하는지, 어떻게 옮기는지 안내합니다.
• 03 slima-mcp 버전은 어떻게 동작하는가 0.3.0(2026-09-09). 서버는 낡은 클라이언트를 막지 않고, 낡은 클라이언트는 호출할 도구가 적을 뿐입니다. 버전 확인과 업그레이드 방법.

도구 레퍼런스

• 01 책 관리 도구 (5종) Slima MCP가 제공하는 책 단위 도구 5종: create_book / list_books / get_book / get_book_structure / get_writing_stats. 각 도구의 입력, 출력, 예시를 정리했습니다.
• 02 파일 조작 도구 read_file / edit_file / write_file / create_file / delete_file / append_to_file / search_content의 인자와 동작, 그리고 이 묶음이 손대지 못하는 파일 종류.
• 03 AI 리더 도구 (2종) AI 베타 리더를 외부에서 호출할 수 있는 두 가지 MCP 도구, list_personas와 analyze_chapter. 입력값, 반환값, Slima 내부 리딩과의 대응 관계를 정리했습니다.
• 04 구조화 편집 도구(update_*) update_* 도구로 비트 보드, 연표, 대본, 관계도, 세계 지도를 고치는 방법. 한 번에 한 작업, op_ref 연결, 전부 아니면 전무.
• 05 메모와 코멘트 도구 외부 AI가 메모를 읽고 쓰고 코멘트 흐름에 참여하게 하기: list_notes / create_note / list_comments / create_comment / resolve_comment / reopen_comment.
• 06 의미 검색과 전문 검색 semantic_search는 의미로 찾고 search_content는 글자로 찾습니다. 어떤 질문을 어느 도구에 던질지, 색인은 어떻게 만들어지는지.

파일 유형과 권한

• 01 MCP가 파일 종류별로 할 수 있는 일 전체 대조표: 산문 파일은 통째 쓰기, 구조화 파일 다섯 종류는 필드 단위 도구, 어떤 종류는 둘 다 불가. 예전 시나리오 스튜디오 작품의 경로 규칙까지.
• 02 구조화 파일 보호: 거부 메시지 읽는 법 AI_READONLY_FILE_TYPE, SUBSCRIPTION_REQUIRED, INVALID_PATH, FOLDER_NOT_EMPTY가 각각 무슨 뜻이고 다음에 무엇을 해야 하는지.
• 03 특정 파일에서 다르게 동작하는 도구들 read_file, search_content, semantic_search, analyze_chapter, get_writing_stats, create_file, delete_file의 예외 동작과 대처법.

고급: 스키마와 셀프 호스팅

• 01 schema 리소스로 작품 권한 정확하게 조회하기 MCP 리소스 `slima://books/{book_token}/schema`는 해당 작품의 정확한 read-only / writable 경로 규칙을 반환합니다 — AI는 이를 통해 특정 경로에 쓸 수 있는지 미리 확인할 수 있습니다.
• 02 Cloudflare Worker 직접 호스팅 (고급) Slima MCP 서버는 Cloudflare Worker에서 동작하는 오픈 소스 프로젝트입니다. Fork 후 직접 배포하여 OAuth 흐름을 커스터마이즈하거나 자체 미들웨어를 추가할 수 있습니다.
• 03 가이드와 글쓰기 스킬 get_capabilities, Slima 자신의 조작 가이드와 글쓰기 스킬: Slima가 자기 규칙을 여러분의 AI 도구에 건네주는 방식.
• 04 AI에게 관계도를 보여주기 view_relationship_map은 그림과 읽을 수 있는 요약을 함께 돌려줍니다. .map 원본 JSON을 읽는 것보다 낫고, 만나게 될 응답은 네 가지입니다.

문제 해결

• 01 MCP 연결 실패: 401 / Authorization header MCP 연결 실패의 가장 흔한 원인은 401 Unauthorized입니다. 토큰 만료 / 설정 오류 / WWW-Authenticate flow 실패 등 상황별 진단 방법을 정리합니다.
• 02 토큰 만료 또는 재인증이 필요할 때 Slima MCP 토큰은 OAuth 로그인으로 발급되며 일정 주기로 만료됩니다. 만료되면 401이 반환되고, 재인증(웹에서는 보통 자동)으로 해결됩니다. 만료 확인 및 갱신 방법을 안내합니다.
• 03 쓰기가 거부될 때 AI_READONLY_FILE_TYPE, SUBSCRIPTION_REQUIRED, INVALID_PATH, FOLDER_NOT_EMPTY가 각각 무슨 뜻인지, 그리고 성공했는데 파일이 비어 있는 create_file의 경우.
• 04 고급: OAuth 흐름 디버깅하기 OAuth 9단계 흐름: DCR → authorize → callback → token → mcp. `wrangler tail` / curl로 어느 단계에서 실패하는지 추적합니다.