Overleaf

Acesse e analise projetos do Overleaf e arquivos LaTeX por meio da integração com Git.

Documentação

Servidor MCP Overleaf

Um servidor MCP (Model Context Protocol) que fornece acesso a projetos Overleaf por meio da integração com Git. Isso permite que o Claude e outros clientes MCP leiam arquivos LaTeX, analisem a estrutura do documento, extraiam conteúdo e gravem arquivos de e para projetos Overleaf.

Recursos

📄 Gerenciamento de Arquivos: Liste, leia e grave arquivos de e para projetos Overleaf
📋 Estrutura do Documento: Analise seções e subseções LaTeX
🔍 Extração de Conteúdo: Extraia seções específicas por título
📊 Resumo do Projeto: Obtenha uma visão geral do status e da estrutura do projeto
🏗️ Suporte a Múltiplos Projetos: Gerencie vários projetos Overleaf

Início Rápido (recomendado)

Sem clone, sem npm install. Adicione este bloco à configuração do Claude Desktop e reinicie o Claude Desktop.

Localização do arquivo de configuração

SO	Caminho
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Linux	`~/.config/claude/claude_desktop_config.json`

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 — O Claude Desktop no Windows precisa de cmd /c para encontrar npx:

{
  "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"
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas overleaf devem aparecer no menu 🔧.

Configuração de Múltiplos Projetos

O Início Rápido com variáveis de ambiente lida apenas com um único projeto. Para vários projetos, coloque um arquivo projects.json no diretório de configuração do usuário e omita o bloco env na configuração do Claude Desktop.

Localização do arquivo

SO	Caminho
Windows	`%APPDATA%\overleaf-mcp\projects.json`
macOS / Linux	`~/.config/overleaf-mcp/projects.json` (ou `$XDG_CONFIG_HOME/overleaf-mcp/projects.json` se definido)

Conteúdo do arquivo

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

Configuração do Claude Desktop — igual ao Início Rápido, mas sem o bloco env:

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

(Coloque cmd /c no macOS / Linux.)

Referencie um projeto específico nas chamadas de ferramenta com projectName:

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

Se projectName for omitido, a entrada default será usada. Para colocar projects.json em outro lugar que não seja o local padrão, aponte OVERLEAF_PROJECTS_CONFIG=/absolute/path/projects.json para ele a partir do bloco env.

Obtendo Credenciais do Overleaf

ID do Projeto — abra seu projeto Overleaf; o ID está na URL: https://www.overleaf.com/project/[PROJECT_ID]
Token Git — Overleaf → Configurações da Conta → Integração Git → "Criar Token"

Referência de Configuração

O servidor seleciona a primeira fonte de configuração correspondente:

Variáveis de ambiente (projeto único) — OVERLEAF_PROJECT_ID + OVERLEAF_GIT_TOKEN. Opcional: OVERLEAF_PROJECT_NAME para o nome de exibição.
Token de um arquivo — defina OVERLEAF_PROJECT_ID junto com OVERLEAF_GIT_TOKEN_FILE=/path/to/token.txt (em vez de OVERLEAF_GIT_TOKEN). Útil quando você não quer o token no JSON do Claude Desktop. O arquivo é lido uma vez na inicialização e qualquer espaço em branco/nova linha final é removido.
Arquivo de múltiplos projetos — OVERLEAF_PROJECTS_CONFIG=/absolute/path/projects.json.
Diretório de configuração do usuário — projects.json em:
- Windows: %APPDATA%\overleaf-mcp\projects.json
- macOS / Linux: $XDG_CONFIG_HOME/overleaf-mcp/projects.json (padrão: ~/.config/overleaf-mcp/projects.json)
Diretório de trabalho — ./projects.json
Diretório do pacote — projects.json ao lado do script do servidor (legado, para instalações baseadas em clone).

Quando as variáveis de ambiente estão definidas e um arquivo também está presente, as variáveis de ambiente vencem e um aviso é registrado no stderr para que o sombreamento seja visível.

Esquema `projects.json` (múltiplos projetos)

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

Em seguida, especifique o projeto nas chamadas de ferramenta: projectName: "paper2".

Desenvolvimento Local

Se você quiser modificar o servidor, testar alterações antes de publicar ou usá-lo sem que o pacote npm esteja disponível, você tem três opções de instalação local.

Opção 1 — Execute o script clonado diretamente

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

Em seguida, aponte o Claude Desktop para o script e passe as credenciais via variáveis de ambiente (o mesmo caminho de carregamento que o pacote npm usa):

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

No Windows, args deve usar "C:\\Users\\you\\OverleafMCP\\overleaf-mcp-server.js".

Se você preferir usar um arquivo de múltiplos projetos:

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

projects.json ao lado do script é o fallback de menor prioridade, então isso ainda funciona sem variáveis de ambiente.

Opção 2 — Teste o artefato npm empacotado localmente

Valida quase o mesmo caminho de código que os usuários encontram no registro público, útil antes de publicar uma versão:

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

Aponte o Claude Desktop para o tarball. Observe o --package= explícito e o nome do bin — npx -y <tarball-path> não funciona no npm 10+ (o caminho é detectado incorretamente como um executável):

{
  "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_..."
      }
    }
  }
}

No macOS / Linux, remova o wrapper cmd /c: "command": "npx", "args": ["-y", "--package=/abs/path/to/...tgz", "overleaf-mcp"].

Opção 3 — Teste rápido do protocolo MCP no shell

Não é necessário Claude Desktop:

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

Você deve ver Overleaf MCP server running on stdio no stderr. O processo permanece aberto aguardando JSON-RPC no stdin; Ctrl+C para sair.

Ferramentas Disponíveis

`list_projects`

Liste todos os projetos configurados.

`list_files`

Liste arquivos em um projeto (padrão: arquivos .tex).

extension: Filtro de extensão de arquivo (opcional)
projectName: Identificador do projeto (opcional, padrão: "default")

`read_file`

Leia um arquivo específico do projeto.

filePath: Caminho para o arquivo (obrigatório)
projectName: Identificador do projeto (opcional)

`get_sections`

Obtenha todas as seções de um arquivo LaTeX.

filePath: Caminho para o arquivo LaTeX (obrigatório)
projectName: Identificador do projeto (opcional)

`get_section_content`

Obtenha o conteúdo de uma seção específica.

filePath: Caminho para o arquivo LaTeX (obrigatório)
sectionTitle: Título da seção (obrigatório)
projectName: Identificador do projeto (opcional)

`status_summary`

Obtenha um resumo abrangente do status do projeto.

projectName: Identificador do projeto (opcional)

`write_file`

Grave o conteúdo completo de um arquivo no projeto.

filePath: Caminho para o arquivo (obrigatório)
content: Conteúdo a ser gravado no arquivo (obrigatório)
commitMessage: Mensagem de commit (obrigatório)
projectName: Identificador do projeto (opcional)

`write_section`

Grave o conteúdo de uma seção específica no projeto.

filePath: Caminho para o arquivo (obrigatório)
sectionTitle: Título da seção (obrigatório)
newContent: Conteúdo de substituição para a seção, incluindo o cabeçalho da seção (obrigatório)
commitMessage: Mensagem de commit (obrigatório)
projectName: Identificador do projeto (opcional)

Exemplos de Uso

# 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: "..."

Notas de Segurança

O token Git do Overleaf concede acesso total de leitura/gravação ao seu projeto — trate-o como uma senha.
Prefira OVERLEAF_GIT_TOKEN_FILE em vez de incorporar o token no JSON do Claude Desktop se o seu arquivo de configuração for copiado ou sincronizado.
projects.json é .gitignored neste repositório. Nunca faça commit de IDs de projeto reais ou tokens Git.
Os caminhos de arquivo fornecidos por meio de chamadas de ferramenta MCP são restritos ao diretório do projeto clonado; travessia .. e caminhos absolutos são rejeitados.

Licença

Licença MIT