overleaf-claude-mcp

Claude를 Overleaf 계정에 연결하세요. Claude는 프로젝트를 나열하고, 하나를 선택하고, LaTeX 및 그림을 읽고, 파일을 편집하고, 컴파일하고, PDF를 다시 가져올 수 있습니다.

Overleaf는 무료 요금제에서 공개 API를 제공하지 않습니다. Git 브리지와 Dropbox 동기화는 프리미엄 기능입니다. 따라서 이 서버는 Overleaf 웹 앱이 사용하는 것과 동일한 내부 HTTP 및 소켓 엔드포인트를 사용하며, 한 번 생성한 브라우저 세션으로 인증합니다. 모든 엔드포인트는 Overleaf 자체 JavaScript 번들에서 읽어낸 다음 실제 계정으로 테스트했습니다. 검증된 엔드포인트를 참조하세요.

튜토리얼

필요한 것

• Node 20 이상 (node -v)

• Chrome 또는 Edge 설치

• Overleaf 계정 (무료 요금제로 충분)

• Claude Code (claude --version) 또는 Claude Desktop

1단계: 설정 실행

이 폴더에서 Windows의 경우:

setup.cmd

macOS 또는 Linux의 경우:

./setup.sh

설정은 다섯 단계를 실행하고 각 단계를 출력합니다:

1. 의존성 설치

2. dist/로 빌드

3. 작동하는 Overleaf 세션이 있는지 확인합니다. 없으면 Overleaf 로그인 페이지가 브라우저 창으로 열립니다.

4. 연결이 작동하는지 증명하기 위해 실제 프로젝트 하나를 다시 읽습니다.

5. 서버를 Claude Code에 등록할지 제안합니다.

2단계: 브라우저가 열리면 로그인

브라우저 창은 실제 Chrome입니다. 2FA를 포함해 평소와 같은 방식으로 로그인하세요. 어떤 것도 비밀번호를 대신 입력하지 않으며, 비밀번호는 절대 읽거나 저장되지 않습니다.

프로젝트 목록에 도달하면 창이 자동으로 닫히고 설정이 계속됩니다. 세션 쿠키는 ~/.overleaf-claude-mcp/session.json에 저장됩니다.

이 파일은 Overleaf 계정에 대한 전체 액세스 권한과 동일합니다. gitignore 처리되며 0600 권한으로 저장됩니다. 공유하거나 커밋하지 마세요.

3단계: 설정이 서버를 등록하도록 하기

5단계에서 프롬프트가 표시됩니다:

      Register this server with Claude Code now? [y/N]

y라고 답하면 다음이 실행됩니다:

claude mcp add overleaf -- node C:/CoolYEAH/overleaf-claude-mcp/dist/index.js

건너뛰었거나 다른 클라이언트를 사용한다면 직접 등록하세요. Claude Code의 경우 위 명령을 실행하세요. Claude Desktop의 경우 Windows에서는 %APPDATA%\Claude\claude_desktop_config.json을(를), macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json을(를) 편집하세요:

{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": ["C:/CoolYEAH/overleaf-claude-mcp/dist/index.js"]
    }
  }
}

4단계: Claude 다시 시작

MCP 서버는 시작 시에만 인식됩니다. Claude Code 또는 Claude Desktop을 종료하고 다시 여세요.

로드되었는지 확인하세요:

claude mcp list

overleaf가 연결됨으로 표시되어야 합니다. Claude Code 세션에서 /mcp도 동일하게 표시됩니다.

5단계: 사용하기

평범한 언어로 요청하기만 하면 됩니다. Claude가 도구를 직접 선택합니다.

List my Overleaf projects

Select the Efficient Reasoning project

Read sections/methodology.tex

In sections/results.tex, change "Table 1" to "Table~\ref{tab:main}"

Compile it and tell me what the LaTeX errors are

Show me figures/fig1.png

Save the compiled PDF to C:/tmp/paper.pdf

프로젝트를 한 번 선택하면 그 상태가 유지됩니다. 선택 항목은 ~/.overleaf-claude-mcp/state.json에 저장되어 다시 시작한 후에도 유지되므로, 전환하기 전까지 이후의 모든 요청은 해당 프로젝트에 적용됩니다. 전환하지 않고 한 번의 요청으로 다른 프로젝트를 작업하려면 이름을 지정하세요: "my thesis 프로젝트에서 main.tex을 읽어줘".

Related MCP server: claudeleaf

트리거 방법

슬래시 명령도 입력할 내용도 없습니다. Claude는 도구 설명을 읽고 요청이 일치하면 도구를 호출합니다. Overleaf 또는 이미 선택한 프로젝트나 파일을 언급하기만 하면 됩니다.

Claude가 도구를 사용하지 않는다면 일반적인 원인은 등록 후 다시 시작하지 않았거나 아직 선택된 프로젝트가 없는 것입니다. 확인하려면 "선택된 Overleaf 프로젝트가 무엇인가요?"라고 물어보세요.

도구

overleaf_select_project는 프로젝트 id 또는 프로젝트 이름의 일부를 받습니다. 이름이 둘 이상의 프로젝트와 일치하면 추측하지 않고 후보를 나열합니다. overleaf_delete는 confirm이 true가 아니면 실행되지 않으므로 Claude가 실수로 파일을 삭제할 수 없습니다.

문제 해결

"No Overleaf session at ..." — 아직 로그인하지 않았거나 세션이 만료되었습니다. npm run login 또는 setup.cmd를 다시 실행하세요.

Claude가 도구를 인식하지 못합니다 — 등록 후 Claude를 다시 시작하지 않았습니다. claude mcp list를 확인하세요.

도구가 갑자기 실패합니다 — Overleaf가 엔드포인트를 변경했을 수 있습니다. npm run recon을 실행하세요. 이 명령은 각 엔드포인트를 읽기 전용으로 검사하고 정확히 어떤 호출이 실패했는지 알려줍니다.

Claude 없이 터미널에서 설정을 확인하세요:

npm run read -- "Efficient Reasoning"

일치하는 프로젝트의 파일 트리와 모든 섹션 제목을 출력합니다. 단일 파일을 덤프하려면 경로를 추가하세요:

npm run read -- "Efficient Reasoning" sections/methodology.tex

언제든 설정을 다시 실행하세요. 작동하는 세션을 재사용하고 연결을 다시 확인하므로 상태 점검 역할도 합니다.

작동 방식

파일 트리는 Overleaf의 소켓 연결에서 가져옵니다. 엔티티 id를 제공하는 유일한 소스이고, 쓰기에는 id가 필요하기 때문입니다. 핸드셰이크는 GET /socket.io/1/?projectId=<id>이며, 이는 socket.io 0.9 프레이밍입니다. 그러면 서버가 rootFolder, 문서 id, 파일 해시를 포함한 전체 프로젝트와 함께 joinProjectResponse를 푸시합니다. 트리는 OVERLEAF_TREE_TTL_MS(기본값 15초) 동안 캐시되며 모든 쓰기 후 무효화됩니다.

텍스트 파일은 문서별로 읽히므로 읽기는 항상 현재 상태를 반영합니다. overleaf_grep은 대신 프로젝트 아카이브를 읽기 때문에 전체 프로젝트 검색은 파일당 한 번이 아니라 요청 한 번으로 처리됩니다.

쓰기는 업로드 엔드포인트를 통해 이루어집니다. 기존 이름 위에 업로드하는 것은 제자리 업데이트입니다. 엔티티 id가 보존되므로 Overleaf 기록과 문서의 다른 사용자도 계속 작동합니다. 누락된 상위 폴더가 먼저 생성됩니다.

검증된 엔드포인트

실제 계정으로 라이브 확인되었으며, 추측이 아닙니다:

:type은 doc, file 또는 folder입니다.

스크립트

npm run smoke는 claude-mcp-smoketest라는 프로젝트를 만든 다음 쓰기, 덮어쓰기, 이미지 업로드, 이름 바꾸기, 이동, 삭제, 컴파일을 실행합니다. 검사할 수 있도록 프로젝트를 계정에 남겨 둡니다. 작업이 끝나면 휴지통에 버리세요.

구성

모두 선택 사항입니다. .env.example을 참조하세요.

제한 사항

이 중 어떤 것도 지원되는 API가 아니며 Overleaf는 언제든 이를 변경할 수 있습니다. 자신의 계정에만 사용하세요. 실시간 공동 편집은 구현되어 있지 않습니다. 쓰기는 문자 단위 연산을 보내는 대신 문서 전체를 교체하므로, 다른 사람이 입력하는 동안 파일에 쓰지 마세요.