Overleaf MCP 서버

Git 통합을 통해 Overleaf 프로젝트에 대한 액세스를 제공하는 MCP(Model Context Protocol) 서버입니다. 이를 통해 Claude 및 기타 MCP 클라이언트는 LaTeX 파일을 읽고, 문서 구조를 분석하고, 콘텐츠를 추출하며, Overleaf 프로젝트로 파일을 쓰고 읽을 수 있습니다.

기능

• 📄 파일 관리: Overleaf 프로젝트에서 파일을 나열, 읽기 및 쓰기

• 📋 문서 구조: LaTeX 섹션 및 서브섹션 파싱

• 🔍 콘텐츠 추출: 제목별로 특정 섹션 추출

• 📊 프로젝트 요약: 프로젝트 상태 및 구조 개요 확인

• 🏗️ 다중 프로젝트 지원: 여러 Overleaf 프로젝트 관리

Related MCP server: Github MCP Server

빠른 시작 (권장)

복제나 npm install이 필요 없습니다. 이 블록을 Claude Desktop 설정에 추가하고 Claude Desktop을 다시 시작하세요.

설정 파일 위치

macOS / Linux

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "@mjyoo2/overleaf-mcp"],
      "env": {
        "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
        "OVERLEAF_GIT_TOKEN": "YOUR_OVERLEAF_GIT_TOKEN"
      }
    }
  }
}

Windows — Windows용 Claude Desktop은 npx를 찾기 위해 cmd /c가 필요합니다:

{
  "mcpServers": {
    "overleaf": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@mjyoo2/overleaf-mcp"],
      "env": {
        "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
        "OVERLEAF_GIT_TOKEN": "YOUR_OVERLEAF_GIT_TOKEN"
      }
    }
  }
}

Claude Desktop을 다시 시작하세요. 🔧 메뉴에 overleaf 도구가 나타나야 합니다.

다중 프로젝트 설정

환경 변수를 이용한 빠른 시작은 단일 프로젝트만 처리합니다. 여러 프로젝트를 사용하려면 projects.json 파일을 사용자 설정 디렉토리에 넣고 Claude Desktop 설정에서 env 블록을 건너뛰세요.

파일 위치

파일 내용

{
  "projects": {
    "default": {
      "name": "Main Paper",
      "projectId": "...",
      "gitToken": "olp_..."
    },
    "thesis": {
      "name": "PhD Thesis",
      "projectId": "...",
      "gitToken": "olp_..."
    }
  }
}

Claude Desktop 설정 — 빠른 시작과 동일하지만 env 블록은 없습니다:

{
  "mcpServers": {
    "overleaf": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@mjyoo2/overleaf-mcp"]
    }
  }
}

(macOS / Linux에서는 cmd /c를 제거하세요.)

도구 호출 시 projectName으로 특정 프로젝트를 참조하세요:

Use read_file with filePath: "main.tex", projectName: "thesis"

projectName이 생략되면 default 항목이 사용됩니다. projects.json을 표준 위치가 아닌 다른 곳에 두려면 env 블록에서 OVERLEAF_PROJECTS_CONFIG=/absolute/path/projects.json을 지정하세요.

Overleaf 자격 증명 얻기

1. 프로젝트 ID — Overleaf 프로젝트를 엽니다. ID는 URL에 있습니다: https://www.overleaf.com/project/[PROJECT_ID]

2. Git 토큰 — Overleaf → 계정 설정(Account Settings) → Git 통합(Git Integration) → "토큰 생성(Create Token)"

설정 참조

서버는 첫 번째로 일치하는 설정 소스를 선택합니다:

1. 환경 변수 (단일 프로젝트) — OVERLEAF_PROJECT_ID + OVERLEAF_GIT_TOKEN. 선택 사항: 표시 이름을 위한 OVERLEAF_PROJECT_NAME.

2. 파일로부터의 토큰 — OVERLEAF_PROJECT_ID와 함께 OVERLEAF_GIT_TOKEN_FILE=/path/to/token.txt를 설정합니다 (OVERLEAF_GIT_TOKEN 대신). Claude Desktop JSON에 토큰을 넣고 싶지 않을 때 유용합니다. 파일은 시작 시 한 번 읽히며 후행 공백/줄 바꿈은 제거됩니다.

3. 다중 프로젝트 파일 — OVERLEAF_PROJECTS_CONFIG=/absolute/path/projects.json.

4. 사용자 설정 디렉토리 — 다음 위치의 projects.json:

   • Windows: %APPDATA%\overleaf-mcp\projects.json

   • macOS / Linux: $XDG_CONFIG_HOME/overleaf-mcp/projects.json (기본값 ~/.config/overleaf-mcp/projects.json)

5. 작업 디렉토리 — ./projects.json

6. 패키지 디렉토리 — 서버 스크립트 옆의 projects.json (레거시, 복제 기반 설치용).

환경 변수가 설정되어 있고 파일도 존재하는 경우, 환경 변수가 우선하며 섀도잉을 확인할 수 있도록 stderr에 알림이 기록됩니다.

projects.json 스키마 (다중 프로젝트)

{
  "projects": {
    "default": {
      "name": "Main Paper",
      "projectId": "...",
      "gitToken": "olp_..."
    },
    "paper2": {
      "name": "Second Paper",
      "projectId": "...",
      "gitToken": "olp_..."
    }
  }
}

그런 다음 도구 호출에서 프로젝트를 지정하세요: projectName: "paper2".

로컬 개발

서버를 수정하거나, 게시하기 전에 변경 사항을 테스트하거나, npm 패키지 없이 사용하려면 세 가지 로컬 설치 옵션이 있습니다.

옵션 1 — 복제된 스크립트를 직접 실행

git clone https://github.com/mjyoo2/OverleafMCP.git
cd OverleafMCP
npm install

그런 다음 Claude Desktop이 스크립트를 가리키도록 하고 환경 변수를 통해 자격 증명을 전달하세요 (npm 패키지가 사용하는 것과 동일한 로더 경로):

{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": ["/absolute/path/to/OverleafMCP/overleaf-mcp-server.js"],
      "env": {
        "OVERLEAF_PROJECT_ID": "...",
        "OVERLEAF_GIT_TOKEN": "olp_..."
      }
    }
  }
}

Windows의 경우 args는 "C:\\Users\\you\\OverleafMCP\\overleaf-mcp-server.js"를 사용해야 합니다.

다중 프로젝트 파일을 사용하려면:

cp projects.example.json projects.json   # then edit it

스크립트 옆의 projects.json은 우선순위가 가장 낮은 대체 수단이므로 환경 변수 없이도 작동합니다.

옵션 2 — 로컬에서 패키징된 npm 아티팩트 테스트

사용자가 공개 레지스트리를 통해 접근하는 경로와 거의 동일한 코드 경로를 검증하며, 릴리스를 푸시하기 전에 유용합니다:

npm pack
# → mjyoo2-overleaf-mcp-<version>.tgz

Claude Desktop이 tarball을 가리키도록 하세요. 명시적인 --package=와 bin 이름을 확인하세요. npx -y <tarball-path>는 npm 10+에서 작동하지 않습니다 (경로가 실행 파일로 잘못 감지됨):

{
  "mcpServers": {
    "overleaf": {
      "command": "cmd",
      "args": [
        "/c", "npx", "-y",
        "--package=C:\\absolute\\path\\to\\mjyoo2-overleaf-mcp-<version>.tgz",
        "overleaf-mcp"
      ],
      "env": {
        "OVERLEAF_PROJECT_ID": "...",
        "OVERLEAF_GIT_TOKEN": "olp_..."
      }
    }
  }
}

macOS / Linux에서는 cmd /c 래퍼를 제거하세요: "command": "npx", "args": ["-y", "--package=/abs/path/to/...tgz", "overleaf-mcp"].

옵션 3 — 셸에서 MCP 프로토콜 스모크 테스트

Claude Desktop이 필요 없습니다:

OVERLEAF_PROJECT_ID=... OVERLEAF_GIT_TOKEN=... node overleaf-mcp-server.js

stderr에 Overleaf MCP server running on stdio가 표시되어야 합니다. 프로세스는 stdin에서 JSON-RPC를 기다리며 열려 있습니다. 종료하려면 Ctrl+C를 누르세요.

사용 가능한 도구

list_projects

설정된 모든 프로젝트를 나열합니다.

list_files

프로젝트의 파일을 나열합니다 (기본값: .tex 파일).

• extension: 파일 확장자 필터 (선택 사항)

• projectName: 프로젝트 식별자 (선택 사항, 기본값 "default")

read_file

프로젝트에서 특정 파일을 읽습니다.

• filePath: 파일 경로 (필수)

• projectName: 프로젝트 식별자 (선택 사항)

get_sections

LaTeX 파일에서 모든 섹션을 가져옵니다.

• filePath: LaTeX 파일 경로 (필수)

• projectName: 프로젝트 식별자 (선택 사항)

get_section_content

특정 섹션의 내용을 가져옵니다.

• filePath: LaTeX 파일 경로 (필수)

• sectionTitle: 섹션 제목 (필수)

• projectName: 프로젝트 식별자 (선택 사항)

status_summary

포괄적인 프로젝트 상태 요약을 가져옵니다.

• projectName: 프로젝트 식별자 (선택 사항)

write_file

파일의 전체 내용을 프로젝트에 씁니다.

• filePath: 파일 경로 (필수)

• content: 파일에 쓸 내용 (필수)

• commitMessage: 커밋 메시지 (필수)

• projectName: 프로젝트 식별자 (선택 사항)

write_section

특정 섹션의 내용을 프로젝트에 씁니다.

• filePath: LaTeX 파일 경로 (필수)

• sectionTitle: 섹션 제목 (필수)

• newContent: 섹션 제목을 포함하여 섹션을 대체할 내용 (필수)

• commitMessage: 커밋 메시지 (필수)

• projectName: 프로젝트 식별자 (선택 사항)

사용 예시

# List all projects
Use the list_projects tool

# Get project overview
Use status_summary tool

# Read main.tex file
Use read_file with filePath: "main.tex"

# Get Introduction section
Use get_section_content with filePath: "main.tex" and sectionTitle: "Introduction"

# List all sections in a file
Use get_sections with filePath: "main.tex"

# Write the full content of a file to the project
Use write_file with filePath: "main.tex", content: "...", commitMessage: "..."

# Write the content of a specific section to the project
Use write_section with filePath: "main.tex", sectionTitle: "Introduction", newContent: "\\section{Introduction}\n...", commitMessage: "..."

보안 참고 사항

• Overleaf Git 토큰은 프로젝트에 대한 전체 읽기/쓰기 권한을 부여하므로 비밀번호처럼 취급하세요.

• 설정 파일이 백업되거나 동기화되는 경우 Claude Desktop JSON에 토큰을 직접 입력하는 것보다 OVERLEAF_GIT_TOKEN_FILE을 사용하는 것을 선호합니다.

• projects.json은 이 저장소에서 .gitignore 처리되어 있습니다. 실제 프로젝트 ID나 Git 토큰을 커밋하지 마세요.

• MCP 도구 호출을 통해 제공된 파일 경로는 복제된 프로젝트 디렉토리로 제한됩니다. .. 탐색 및 절대 경로는 거부됩니다.

라이선스

MIT 라이선스