ragbox로 로컬 파일을 MCP 검색에 연결한다

ragbox는 지정한 폴더의 파일을 색인하고 AI 에이전트가 검색하도록 하는 로컬 검색 증강 생성(RAG) 서비스다. Docker 컨테이너 하나로 실행하며, Model Context Protocol(MCP) 서버와 웹 관리 화면을 제공한다.

파일에서 텍스트를 추출해 청크로 나누고, Ollama나 OpenAI 호환 API 같은 외부 제공자를 이용해 각 청크의 임베딩을 만든다. 데이터는 pgvector 확장을 사용하는 내장 PostgreSQL 데이터베이스 PGlite에 저장하므로 별도 데이터베이스는 필요하지 않다. 폴더의 파일이 추가·변경·삭제되면 이를 감지해 색인을 갱신하며, 변경된 파일은 기본적으로 10초의 대기 시간 뒤 다시 색인한다.

MCP 서버는 HTTP로 실행되며 search 도구 하나를 제공한다. 이 도구는 벡터 검색과 키워드 검색을 함께 사용한다. 웹 화면에서는 색인 진행 상황과 오류를 확인하고, 검색을 시험하거나 설정을 바꿀 수 있다.

PDF, Office 문서, 텍스트·마크업, 데이터 파일, 소스 코드, 이미지와 WAV 오디오 등을 지원한다. MetaTrader 파일(.mq4, .mqh)도 지원하지만 기본값은 비활성화이며, 지원 파일 형식은 설정 화면에서 켜거나 끌 수 있다. PDF는 텍스트 레이어가 있어야 하며 스캔 문서의 OCR은 지원하지 않는다.

시작하려면 Docker를 설치한다. Ollama는 선택 사항으로, 설치하지 않은 경우 ragbox와 함께 컨테이너에서 실행할 수 있다. 설정 스크립트는 색인할 폴더를 묻고 서비스를 시작한 뒤 MCP 클라이언트에 연결할 주소를 안내한다. macOS에서는 Docker 컨테이너가 GPU를 사용할 수 없어 컨테이너 안의 Ollama가 훨씬 느리므로, 더 빠른 색인을 원한다면 스크립트를 실행하기 전에 Ollama를 설치해야 한다. 설정 스크립트는 macOS, Linux, Windows Subsystem for Linux(WSL)에서 동작한다.

저장소를 내려받아 스크립트를 실행하는 방법은 다음과 같다.

git clone https://github.com/ferraridavide/ragbox.git
cd ragbox
./run.sh

Docker Compose를 직접 사용할 수도 있다. 두 방식 모두 /path/to/your/documents를 색인할 폴더로 바꿔야 한다. Ollama가 이미 설치된 경우 임베딩 모델을 내려받고 ragbox를 시작한다.

ollama pull embeddinggemma-2
RAGBOX_DOCS=/path/to/your/documents docker compose up -d --build

Ollama를 컨테이너로 함께 실행하면 첫 시작 때 embeddinggemma-2를 내려받는다. Linux에서 NVIDIA GPU를 사용하려면 docker-compose.ollama.yml의 deploy 섹션 주석을 해제해야 한다.

RAGBOX_DOCS=/path/to/your/documents docker compose -f docker-compose.ollama.yml up -d --build

색인 진행 상황은 기본 주소 http://localhost:8080에서 볼 수 있다. 포트를 바꾸려면 RAGBOX_HOST_PORT를 설정한다. MCP 주소는 http://localhost:8080/mcp이며 Streamable HTTP 전송 방식을 사용한다. Claude Code에는 다음 명령으로 연결할 수 있다.

claude mcp add --transport http ragbox http://localhost:8080/mcp

검색 도구는 필수 인수 query와 선택 인수 limit, path_prefix를 받는다. limit은 결과 최대 개수로 1~50 범위이며 기본값은 8이다. path_prefix를 지정하면 해당 폴더의 파일만 검색한다.

설정은 웹 화면에서 바꾸거나 docker-compose.yml의 환경 변수로 초기값을 지정할 수 있다. 웹 화면에서 저장한 값은 환경 변수보다 우선한다. 임베딩 제공자는 기본적으로 ollama이며, openai를 선택하면 OpenAI 호환 API를 사용할 수 있다. 임베딩 모델을 바꾸면 색인을 다시 만든다. MCP 토큰을 설정한 경우 클라이언트는 Authorization: Bearer <token> 헤더를 보내야 한다.

웹 화면에는 인증 기능이 없다. 기본 docker-compose.yml 설정은 ragbox를 127.0.0.1에서만 사용할 수 있게 한다. 데이터 볼륨마다 ragbox 컨테이너는 하나만 실행해야 한다. Linux에서는 컨테이너가 사용자 ID 1000으로 실행되므로 해당 사용자가 마운트한 폴더를 읽을 수 있어야 한다. Linux의 기본 Ollama 설치는 127.0.0.1에서만 연결을 받기 때문에 컨테이너가 접근하지 못할 수 있다. 이 경우 Ollama 서비스에 OLLAMA_HOST=0.0.0.0을 설정하거나 Ollama용 Compose 파일을 사용한다.

ragbox는 MIT License로 제공된다. 파일 파싱과 청킹 코드 일부는 같은 라이선스를 사용하는 knowledge-rag에서 가져왔다. 자세한 내용은 LICENSE에서 확인할 수 있다.