# MCP Local RAG
[](https://github.com/shinpr/mcp-local-rag)
[](https://www.npmjs.com/package/mcp-local-rag)
[](https://opensource.org/licenses/MIT)
[](https://registry.modelcontextprotocol.io/)
English |
简体中文 |
Deutsch |
Español |
Português (Brasil) |
Français
Pesquise documentos privados usando um cliente MCP ou o terminal sem enviá-los a uma API de embeddings.
O mcp-local-rag indexa arquivos PDF, DOCX, Markdown e texto no seu computador. A busca combina similaridade semântica e correspondência por palavras-chave. Assim, leva em conta tanto o sentido da consulta quanto termos técnicos exatos, como nomes de APIs, classes e códigos de erro.
## Recursos
- **Execução local:** O processamento dos documentos, os embeddings, o armazenamento e a busca acontecem no seu computador. Depois do primeiro download do modelo, a importação de texto e as buscas funcionam offline.
- **Busca híbrida:** A recuperação semântica encontra conceitos relacionados, enquanto a correspondência por palavras-chave dá mais peso a termos técnicos exatos.
- **Embeddings configuráveis:** Escolha um modelo de embeddings do Hugging Face adequado ao idioma e à área dos seus documentos.
- **Divisão semântica:** Os documentos são divididos nas mudanças de assunto, não por uma quantidade fixa de caracteres. Blocos de código Markdown permanecem intactos.
- **MCP e CLI:** Use o mesmo índice em uma ferramenta de programação com IA ou diretamente no terminal.
Não é necessário ter chave de API, Docker, Python nem banco de dados externo.
## Início rápido
### Requisitos
- Node.js 22 ou mais recente
- Acesso à internet no primeiro uso para baixar o pacote npm e o modelo de embeddings
- Um diretório com os documentos que você quer pesquisar
Defina `BASE_DIR` com o caminho desse diretório. Ele também funciona como limite de segurança para as operações com arquivos. Substitua `/absolute/path/to/your/documents` nos exemplos pelo caminho absoluto do diretório.
O mcp-local-rag usa o protocolo MCP padrão por meio de um servidor stdio local. Assim, ele funciona com ferramentas de programação com IA e outros hosts MCP compatíveis com servidores MCP locais.
Use um dos exemplos abaixo ou registre `npx -y mcp-local-rag` e defina `BASE_DIR` no formato de configuração MCP do seu cliente.
**Claude Code:** Execute este comando:
```bash
claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag
```
**Codex:** Adicione a `~/.codex/config.toml`:
```toml
[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]
[mcp_servers.local-rag.env]
BASE_DIR = "/absolute/path/to/your/documents"
```
**OpenCode:** Adicione a `~/.config/opencode/opencode.json` (ou `opencode.jsonc`):
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"local-rag": {
"type": "local",
"command": ["npx", "-y", "mcp-local-rag"],
"environment": {
"BASE_DIR": "/absolute/path/to/your/documents"
}
}
}
}
```
**Cursor:** Adicione a `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"local-rag": {
"command": "npx",
"args": ["-y", "mcp-local-rag"],
"env": {
"BASE_DIR": "/absolute/path/to/your/documents"
}
}
}
}
```
Reinicie o cliente e peça para ele criar o índice:
```text
Sincronize todos os documentos do diretório raiz configurado e aguarde a conclusão.
```
A primeira sincronização baixa o modelo de embeddings padrão (cerca de 90 MB). O início da importação pode levar de 1 a 2 minutos. Nas próximas execuções, o cache local será usado.
Quando a sincronização terminar, faça uma pergunta:
```text
O que a documentação da API diz sobre autenticação?
```
### Início rápido pela CLI
Para usar a CLI sem um cliente MCP:
```bash
npx mcp-local-rag ingest ./docs/
npx mcp-local-rag query "API de autenticação"
```
Por padrão, a CLI usa o diretório atual como raiz dos documentos. Execute os dois comandos no mesmo diretório para que usem o mesmo índice padrão ou defina `BASE_DIR` e `DB_PATH` explicitamente.
## Por que este projeto existe
Alguns conjuntos de documentos não podem ser enviados a um serviço de embeddings hospedado devido a requisitos de confidencialidade ou políticas da organização. Mantendo o índice local, esses documentos continuam pesquisáveis sem gerar custo de API por consulta.
Uma busca puramente semântica pode ignorar identificadores exatos que são importantes na documentação técnica. O reordenamento por palavras-chave mantém esses termos visíveis sem abrir mão das consultas em linguagem natural.
## Conteúdo compatível
| Entrada | Como importar |
|---|---|
| PDF, DOCX, TXT, Markdown | Importação de arquivo ou sincronização de diretório |
| HTML já obtido pelo cliente | `ingest_data`; limpo com Readability e convertido para Markdown |
| Texto simples ou Markdown em memória | `ingest_data` com um identificador de origem estável |
O servidor não busca HTML por conta própria. Um cliente MCP pode obter uma página e enviar o HTML para `ingest_data`.
A importação de arquivos não aceita Excel, PowerPoint, imagens avulsas nem extensões de código-fonte. Opcionalmente, arquivos PDF podem usar um modelo visual local para descrever figuras, mas esse recurso não é OCR nem busca de imagens.
## Ferramentas MCP
| Ferramenta | Finalidade |
|---|---|
| `sync_start` | Sincronizar o índice com todos os diretórios raiz configurados ou com um caminho |
| `sync_status` | Consultar uma sincronização em andamento |
| `ingest_file` | Importar ou substituir um arquivo |
| `ingest_data` | Importar texto, Markdown ou HTML que já esteja disponível no cliente |
| `query_documents` | Pesquisar com correspondência semântica e reforço por palavras-chave |
| `read_chunk_neighbors` | Ler os fragmentos próximos a um resultado de busca |
| `list_files` | Mostrar os arquivos compatíveis e o estado de importação |
| `delete_file` | Excluir um arquivo indexado ou um item de `ingest_data` |
| `status` | Mostrar o estado do índice e da busca |
### Sincronizar um diretório raiz
`sync_start` importa arquivos novos e alterados, ignora os que são idênticos byte a byte e remove do índice os arquivos que deixaram de existir:
```text
Sincronize todo o conteúdo dos diretórios raiz configurados e aguarde a conclusão.
```
A ferramenta retorna um `jobId` imediatamente. O cliente deve consultar `sync_status` até o estado mudar para `succeeded` ou `failed`. Um PDF alterado mantém o perfil visual com que foi indexado; um PDF sem perfil registrado continua apenas como texto. `sync_start` não altera o perfil.
O processo do servidor mantém apenas o registro de um job de sincronização. Um novo job substitui o registro de outro já concluído, e o registro é descartado quando o servidor reinicia.
### Importar um arquivo
`ingest_file` aceita PDF, DOCX, TXT e Markdown. Os caminhos enviados via MCP devem ser absolutos e permanecer dentro de um diretório raiz configurado:
```text
Importe o documento /Users/me/docs/api-spec.pdf.
```
Importar novamente o mesmo caminho substitui os fragmentos existentes.
### Pesquisar e ler mais contexto
```text
O que a documentação da API diz sobre autenticação?
Encontre o comportamento documentado de ERR_CONNECTION_REFUSED.
```
Os resultados contêm o texto, o caminho de origem, o título, o índice do fragmento e a pontuação de relevância. Se precisar de mais contexto, envie a `read_chunk_neighbors` o `chunkIndex` e o `filePath` ou `source` do resultado:
```text
Leia os fragmentos próximos a esse resultado sobre autenticação.
```
Tanto `query_documents` quanto `list_files` aceitam um prefixo de caminho absoluto opcional em `scope`, ou uma lista de prefixos. Cada prefixo corresponde ao caminho exato e a todos os caminhos abaixo dele.
### Importar HTML
Use `ingest_data` depois que o cliente MCP buscar a página:
```text
Busque https://example.com/docs e importe o HTML.
```
O servidor extrai o artigo principal, converte o conteúdo para Markdown e o armazena com o identificador de origem fornecido. Reutilizar a mesma origem atualiza o conteúdo existente.
Respeite os termos e os direitos autorais do site de origem ao indexar conteúdo externo.
### Figuras em PDF
O modo visual adiciona uma descrição gerada às páginas de PDF com muitas figuras. Ele é opcional e não carrega um modelo visual durante a importação normal.
```text
Importe /Users/me/docs/research-paper.pdf com visual: true.
```
```bash
npx mcp-local-rag ingest ./docs/research-paper.pdf --visual
```
| Perfil | Cache do modelo | Indicação |
|---|---:|---|
| `fast` (padrão) | cerca de 250 MB | Indexação visual leve |
| `quality` | cerca de 1,7 GB | Figuras com rótulos, anotações ou outros textos dentro da imagem |
Selecione o modelo maior com `visualQuality: "quality"` via MCP ou com `--visual-quality quality` pela CLI. Em testes com CPU, a inferência levou cerca do triplo do tempo de `fast`, mas o resultado depende do hardware e das atualizações do modelo.
#### Atualizar as descrições `quality` existentes
A partir da 0.18.4, o `quality` usa o Qwen3.5-2B; versões anteriores usavam o Qwen2.5-VL-3B. As descrições já indexadas mantêm o texto do modelo antigo e o `sync` não as refaz, então reimporte os arquivos que você quiser atualizar:
```bash
npx mcp-local-rag ingest ./docs/research-paper.pdf --visual --visual-quality quality
```
Inclua `--images` se o arquivo foi importado com essa opção, porque uma execução sem ela substitui as imagens armazenadas. O modelo antigo continua no disco. Quando nada mais o usar, apague `onnx-community/Qwen2.5-VL-3B-Instruct-ONNX/` do diretório de cache dos modelos: ``, cujo padrão é `./models/`.
#### Modo visual entre sincronizações
O perfil com que um PDF foi indexado fica registrado e o `sync` o reutiliza: um PDF indexado com `fast` ou `quality` é reimportado com esse mesmo perfil e um PDF sem perfil registrado é importado como texto.
```bash
npx mcp-local-rag sync ./docs/ # manter o perfil registrado de cada PDF
npx mcp-local-rag sync ./docs/ --visual # solicitar fast para todos os PDF do escopo
npx mcp-local-rag sync ./docs/ --visual --visual-quality quality
```
`--visual` substitui os perfis registrados, então também descreve os PDF que foram indexados como texto. Trocar de perfil reimporta o PDF mesmo que o arquivo não tenha mudado; repetir o mesmo comando não faz nada e não carrega modelo algum.
Para desligar as descrições em um caminho, execute `ingest` nele: uma importação normal bem-sucedida limpa o perfil registrado. Para tentar de novo uma página cuja descrição falhou, execute `ingest --visual --visual-quality ` com o perfil desejado — um `ingest` simples o limpa. Se as linhas indexadas de um PDF divergirem quanto ao perfil, o `sync` para antes de alterar qualquer coisa e informa o arquivo; execute-o de novo com `--visual` para definir o perfil.
As descrições são textos auxiliares, não transcrições fiéis. Trate as descrições e o texto recuperado dos documentos como entradas não confiáveis, não como instruções.
## CLI
A CLI usa o mesmo analisador, gerador de embeddings e banco vetorial sem precisar de um cliente MCP:
```bash
npx mcp-local-rag ingest ./docs/
npx mcp-local-rag sync ./docs/
npx mcp-local-rag query "API de autenticação"
npx mcp-local-rag query "autenticação" --scope /docs/api --scope /docs/guide
npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
npx mcp-local-rag list
npx mcp-local-rag status
npx mcp-local-rag delete ./docs/old.pdf
npx mcp-local-rag delete --source "https://example.com/docs"
```
Opções globais, como `--db-path`, `--cache-dir` e `--model-name`, vêm antes do subcomando. As opções próprias do subcomando vêm depois:
```bash
npx mcp-local-rag --db-path ./my-db query "autenticação"
```
Execute `npx mcp-local-rag --help` para consultar a referência completa dos comandos.
A CLI não lê a configuração do cliente MCP. Defina as mesmas variáveis de ambiente ou opções se as duas interfaces precisarem compartilhar um índice. Em particular, `MODEL_NAME` e a opção `--model-name` da CLI devem ser iguais quando usam o mesmo banco de dados.
`query` grava os resultados em stdout como JSON, com a melhor correspondência primeiro, para que você possa encaminhá-los por pipe a outra ferramenta. A definição de cada campo está em [`docs/schema/query-output.schema.json`](docs/schema/query-output.schema.json).
## Ajuste da busca
O reforço por palavras-chave é ativado por padrão. Para acervos que exigem uma seleção mais restrita, também é possível configurar o agrupamento por saltos de relevância e os filtros de distância e de arquivos.
| Variável | Padrão | Descrição |
|----------|---------|-------------|
| `RAG_HYBRID_WEIGHT` | `0.6` | Fator de reforço por palavras-chave (0.0–1.0). 0 desativa o reordenamento por palavras-chave e 1 aplica o reforço máximo. |
| `RAG_GROUPING` | não definido | `similar` mantém o primeiro grupo de relevância; `related` mantém até dois e usa saltos relevantes na distância vetorial como limites. |
| `RAG_MAX_DISTANCE` | não definido | Descarta resultados pouco relevantes, por exemplo, com `0.5`. |
| `RAG_MAX_FILES` | não definido | Limita os resultados aos N arquivos mais bem classificados, por exemplo, `1` para apenas o melhor arquivo. |
Em especificações de API e outros documentos com muitos identificadores, um peso maior para palavras-chave pode melhorar a classificação de termos exatos:
```json
"env": {
"RAG_HYBRID_WEIGHT": "0.7"
}
```
- `0.7`: reordenamento de termos exatos um pouco mais forte que o padrão
- `1.0`: reforço máximo por palavras-chave
## Como funciona
Durante a importação:
1. O analisador extrai o texto do formato de entrada.
2. O divisor semântico encontra as mudanças de assunto e preserva os blocos de código Markdown.
3. O Transformers.js cria os embeddings localmente.
4. O LanceDB armazena os fragmentos, metadados, vetores e o índice de texto completo.
Durante a busca:
1. A consulta é convertida em embedding pelo mesmo modelo.
2. A busca vetorial recupera fragmentos relacionados pelo significado.
3. Quando configurados, os filtros opcionais de distância e os grupos de relevância reduzem os candidatos.
4. As correspondências de texto completo reforçam os termos exatos da consulta.
## Agent Skills
As [Agent Skills](https://agentskills.io/) orientam assistentes de IA na formulação de consultas e na importação de conteúdo:
```bash
npx mcp-local-rag skills install --claude-code
npx mcp-local-rag skills install --claude-code --global
npx mcp-local-rag skills install --codex
```
As skills instaladas cobrem formulação de consultas, refinamento de resultados e importação de HTML. Se uma skill não for ativada automaticamente, peça ao assistente para usar a skill mcp-local-rag de forma explícita.
## Configuração
O servidor MCP lê variáveis de ambiente. A CLI aceita as mesmas variáveis e as opções listadas na tabela; as opções da CLI têm prioridade.
| Variável de ambiente | Opção da CLI | Padrão | Descrição |
|---------------------|----------|---------|-------------|
| `BASE_DIR` | `--base-dir` | Diretório atual | Um diretório raiz; a opção da CLI pode ser repetida em `ingest`, `list` e `sync` |
| `BASE_DIRS` | N/D | não definido | Array JSON de diretórios raiz; tem prioridade sobre `BASE_DIR` |
| `DB_PATH` | `--db-path` | `./lancedb/` | Local do banco de dados vetorial |
| `CACHE_DIR` | `--cache-dir` | `./models/` | Diretório de cache dos modelos |
| `HF_ENDPOINT` | N/D | `https://huggingface.co` | Endereço para download de modelos do Hugging Face; use a URL de um espelho quando downloads diretos estiverem bloqueados |
| `MODEL_NAME` | `--model-name` | `Xenova/all-MiniLM-L6-v2` | Modelo de embeddings do Hugging Face |
| `MAX_FILE_SIZE` | `--max-file-size` | `104857600` (100 MB) | Tamanho máximo do arquivo em bytes |
| `CHUNK_MIN_LENGTH` | `--chunk-min-length` | `50` | Tamanho mínimo de um fragmento comum em caracteres (1–10000); um trecho resultante da divisão para respeitar o limite de tokens do modelo pode ser menor |
| `RAG_DEVICE` | N/D | `cpu` | Dispositivo de execução do ONNX Runtime |
| `RAG_DTYPE` | N/D | `fp32` | Tipo de dados dos embeddings enviado ao modelo selecionado |
### Diretórios raiz (`BASE_DIR` e `BASE_DIRS`)
O mcp-local-rag só permite operações com arquivos dentro dos diretórios raiz configurados. Para usar vários diretórios, `BASE_DIRS` deve ser um array JSON de caminhos não vazios:
```bash
export BASE_DIRS='["/Users/me/Documents/work","/Users/me/Projects/specs"]'
```
A configuração é resolvida nesta ordem:
1. Opções `--base-dir ` da CLI (podem ser repetidas em `ingest`, `list` e `sync`)
2. `BASE_DIRS`
3. `BASE_DIR`
4. Diretório atual
Cada origem substitui a de menor prioridade, em vez de ser combinada com ela. Uma configuração inválida de `BASE_DIRS` produz um erro, sem recorrer a `BASE_DIR` ou ao diretório atual. `status` continua disponível no MCP para que o cliente possa informar o erro de configuração.
```bash
npx mcp-local-rag ingest --base-dir /Users/me/work --base-dir /Users/me/specs /Users/me/work/readme.md
npx mcp-local-rag list --base-dir /Users/me/work --base-dir /Users/me/specs
npx mcp-local-rag sync --base-dir /Users/me/work --base-dir /Users/me/specs
BASE_DIRS='["/Users/me/work","/Users/me/specs"]' npx mcp-local-rag list
```
### Armazenamento e modelos
Por padrão, `DB_PATH` e `CACHE_DIR` são relativos ao diretório de trabalho do processo. Use caminhos absolutos se o cliente MCP puder iniciar o servidor a partir de diretórios de projeto diferentes.
Defina `MODEL_NAME` ou passe `--model-name` para escolher um modelo de embeddings do Hugging Face adequado ao idioma e à área dos seus documentos.
O mcp-local-rag gera embeddings com mean pooling e normalização L2. Ao escolher um modelo, verifique se essas configurações correspondem à configuração de inferência recomendada para esse modelo, pois o tipo de pooling pode afetar a qualidade da busca.
Alterar `MODEL_NAME`, `RAG_DEVICE` ou `RAG_DTYPE` pode deixar os vetores existentes incompatíveis. Depois de mudar a configuração dos embeddings, use um novo `DB_PATH` ou exclua o índice existente e importe os documentos novamente.
Um exemplo de modelo disponível para documentos em português é `Xenova/paraphrase-multilingual-MiniLM-L12-v2`.
## Segurança e operação
- O acesso a arquivos fica restrito aos diretórios raiz definidos em `BASE_DIR`, `BASE_DIRS` ou pela opção `--base-dir` da CLI.
- Links simbólicos que apontam para fora de todos os diretórios raiz configurados são rejeitados.
- O processamento dos documentos e as buscas não fazem solicitações de rede depois que os modelos necessários estão no cache.
- O servidor foi projetado para um único usuário local e não oferece autenticação nem controle de acesso.
- Não execute vários processos de escrita da CLI ou do MCP no mesmo `DB_PATH`. Consultas somente leitura podem ser executadas durante uma sincronização.
- Para fazer backup do índice, copie o diretório `DB_PATH` enquanto não houver nenhum processo de escrita ativo.
Solução de problemas
### "No results found"
Os documentos precisam ser importados primeiro. Execute `"Liste todos os arquivos importados"` para verificar.
### Falha no download do modelo
Verifique a conexão com a internet. Se estiver usando um proxy, revise as configurações de rede. O modelo também pode ser [baixado manualmente](https://huggingface.co/Xenova/all-MiniLM-L6-v2).
### "File too large"
O limite padrão é 100 MB. Divida o arquivo ou aumente `MAX_FILE_SIZE`.
### Consultas lentas
Verifique a quantidade de fragmentos com `status`. Documentos grandes, com muitos fragmentos, podem deixar as consultas mais lentas. Considere dividir arquivos muito grandes.
### "Path outside BASE_DIR"
O caminho precisa estar dentro de um dos diretórios raiz configurados: `BASE_DIR`, uma entrada de `BASE_DIRS` ou um caminho definido por `--base-dir` na CLI. Use um caminho absoluto.
### "BASE_DIRS must be a JSON array..."
`BASE_DIRS` aceita um array JSON com um ou mais caminhos não vazios:
- Válido: `BASE_DIRS='["/Users/me/work","/Users/me/specs"]'`
- Inválido: `BASE_DIRS=/a:/b` (a sintaxe com separadores não é aceita)
- Inválido: `BASE_DIRS='[]'` (array vazio)
### O cliente MCP não mostra as ferramentas
1. Verifique a sintaxe do arquivo de configuração
2. Feche o cliente por completo e abra novamente (Cmd+Q no Mac para o Cursor)
3. Teste diretamente: `npx mcp-local-rag` deve iniciar sem erros
## Como contribuir
Contribuições são bem-vindas. Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para preparar o ambiente e conferir as orientações.
## Licença
Licença MIT. Uso gratuito para fins pessoais e comerciais.
## Artigos do blog
- [Building a Local RAG for Agentic Coding](https://www.norsica.jp/blog/local-rag-agentic-coding): análise técnica do design da divisão semântica e da busca híbrida.
## Agradecimentos
Desenvolvido com o [Model Context Protocol](https://modelcontextprotocol.io/) da Anthropic, o [LanceDB](https://lancedb.com/) e o [Transformers.js](https://huggingface.co/docs/transformers.js).