Paperless-NGX MCP Server의 개요
이것은 최초의 Paperless-ngx MCP 서버인 nloui/paperless-mcp의 유지보수되는 포크입니다. 원본의 마지막 커밋은 2025년 11월 11일이었습니다. Baruch Rothkoff의 포크(baruchiro/paperless-mcp)는 GitHub 스타가 약 149개로 원본의 248개보다 적지만, 계속 출시되고 있는 쪽은 이것입니다. v2.2.1은 2026년 9월 11일에 나왔고, 2026년 10월 29일까지 한 주 동안 npm 패키지 다운로드는 683회로 원본의 171회보다 많았습니다.
문서, 메모, 태그, 거래처, 문서 유형, 사용자 정의 필드, 메일 계정과 규칙을 다루는 약 31개 도구로 Paperless-ngx REST API를 감쌉니다. npx -y @baruchiro/paperless-mcp@latest로 stdio에서 실행하거나, 포트 3000에서 Streamable HTTP와 SSE를 제공하는 Docker 이미지로 실행합니다. Paperless-ngx 인스턴스의 URL과 프로필 페이지에서 받은 API 토큰이 필요합니다. 저장소는 ISC 라이선스입니다.
Paperless-NGX MCP Server 설치 방법
npx -y @baruchiro/paperless-mcp@latestPaperless-NGX MCP Server, 쓸 만한 가치가 있습니까?
이미 편지, 청구서, 세금 서류를 Paperless-ngx에 보관하는 사람에게, 이 서버는 보관소를 에이전트가 검색하고 재정리할 수 있는 것으로 바꿉니다. query_documents는 전문 검색, 유사 문서 조회, 그리고 청구서 번호가 없는 청구서를 모두 찾는 것 같은 구조화된 사용자 정의 필드 쿼리를 그대로 전달합니다. 사람이 웹 인터페이스에서 하는 일의 대부분을 다룹니다.
도구 목록은 읽기를 훨씬 넘어섭니다. bulk_edit_documents는 문서를 병합, 분할, 회전하고, 페이지를 삭제하고, 문서를 삭제하고, 권한을 바꿀 수 있습니다. post_document는 최대 100 MB의 파일을 업로드하고, 메일 도구는 Paperless가 받은편지함에서 무엇을 가져올지 정하는 규칙을 만들고 편집합니다. 명시적인 확인 플래그를 요구하는 것은 메모와 메일 규칙 삭제뿐입니다. 일괄 삭제는 요구하지 않으므로, 클라이언트의 승인 프롬프트가 유일한 방어입니다.
원본 대신 이 포크를 고를 주된 이유는 보안 작업입니다. 버전 2.0.0부터 HTTP 모드는 Bearer 토큰이 없는 요청을 거부합니다. 이전에는 네트워크상의 누구에게든 서버 자체의 키로 대신 동작하던 엔드포인트를 막은 것입니다. 이제 각 HTTP 클라이언트가 자신의 Paperless 토큰을 보내므로, Paperless 권한이 사용자별로 적용됩니다. 파일 경로로 하는 업로드는 PAPERLESS_MCP_UPLOAD_PATHS로 제한하지 않는 한 프로세스가 볼 수 있는 모든 파일을 읽으며, 이 변수는 선택 사항입니다.
약점은 관리자 한 명의 커뮤니티 서버에 흔한 것들입니다. Paperless-ngx v3.0.0은 9 미만의 REST API 버전을 없앴으므로, 오래된 설정은 PAPERLESS_API_VERSION을 설정할 때까지 HTTP 406 오류를 봅니다. 문서는 문서 사이트가 아니라 긴 README입니다. 스캔한 우편물의 문서 텍스트는 신뢰할 수 없는 입력이므로, 이를 읽는 에이전트는 보관소에 대한 쓰기 권한을 쥔 채 프롬프트 인젝션에 노출됩니다.
제 역할을 하는 곳
5년 치 청구서와 영수증을 Paperless-ngx에 보관한 프리랜서
세금 신고 전에 아직 청구서 번호가 없는 2025년 청구서를 모두 찾기
사용자 정의 필드 쿼리를 쓴 query_documents가 빠진 항목을 나열하고, bulk_edit_documents가 후속 처리용 태그를 답니다. 기존 Paperless 설치 위에서 무료이며, 비용은 몇 번의 도구 호출과 각 일괄 편집 검토입니다.
집으로 오는 우편물을 스캔해 Paperless에 넣는 홈랩 운영자
공과금 청구서를 이메일에서 자동으로 가져와 태그를 달도록 메일 규칙 설정하기
에이전트가 메일 계정을 나열한 뒤, 보낸 사람과 제목 필터, 지정할 태그로 create_mail_rule을 호출합니다. 계정 비밀번호는 도구 출력에서 가려지지만, 잘못된 규칙은 실제 받은편지함의 메일을 표시하거나 옮길 수 있습니다.
고객 파일용으로 Paperless를 자체 호스팅하는 작은 회계 사무소
직원 두 명에게 누가 어떤 고객의 문서를 볼 수 있는지 지키는 어시스턴트 주기
Docker 이미지를 HTTP 모드로 실행하고, 각 클라이언트가 자신의 Paperless 토큰을 Bearer 헤더로 보내게 해서 Paperless 권한이 사람별로 적용되게 합니다. 서버는 공용 인터넷에서 떼어 두고 --no-auth는 설정하지 마십시오.
도입 전 확인할 점
- 설정
- PAPERLESS_URL과 PAPERLESS_API_KEY와 함께 npx -y @baruchiro/paperless-mcp@latest를 클라이언트 설정에 추가하거나, 포트 3000에서 HTTP와 SSE를 쓰려면 ghcr.io/baruchiro/paperless-mcp를 실행합니다. README에 Cursor 설치 링크와 Continue 예시가 있으며, 토큰이 있으면 몇 분이면 됩니다.
- 연동
- 약 31개 도구입니다. 문서 나열, 쿼리, 다운로드, 업로드, 썸네일, 메모, 태그, 거래처, 문서 유형, 사용자 정의 필드, 메일 계정과 규칙을 다룹니다. 대략 절반이 쓰기 도구입니다.
- 데이터와 개인정보
- API 토큰이 닿는 모든 것이며, 삭제도 포함됩니다. v2.0.0부터 HTTP 모드에서는 --no-auth를 설정하지 않는 한 요청마다 자체 Bearer 토큰이 있어야 합니다. 파일 경로 업로드는 PAPERLESS_MCP_UPLOAD_PATHS를 설정하지 않으면 어떤 로컬 파일이든 읽습니다. 공개된 GitHub 보안 권고는 없습니다.
- 대규모 사용 시 비용
- 무료입니다. Paperless-ngx는 자체 호스팅이므로 비용은 서버와 모델 토큰뿐입니다. 큰 결과 페이지와 base64 업로드가 컨텍스트를 부풀리는 주된 원인입니다.
- 제한
- Paperless-ngx v3.0.0은 9 미만의 API 버전을 HTTP 406으로 거부합니다. search_documents는 deprecated 상태이며 query_documents가 권장됩니다. 파괴적인 일괄 작업에는 확인 플래그가 없습니다.
좋은 점
- 사용자 정의 필드 쿼리와 메일 규칙을 포함한 약 31개 도구가 있습니다
- v2.0.0부터 HTTP 모드에서 요청마다 Bearer 토큰을 씁니다
- npx와 Docker 이미지가 있고, 실제 Paperless-ngx를 대상으로 종단 간 테스트를 실행합니다
- 원본 저장소와 달리 활발히 유지보수됩니다
아쉬운 점
- 일괄 삭제, 병합, 분할이 확인 플래그 없이 실행됩니다
- 허용 목록을 설정하지 않으면 파일 경로 업로드에 제한이 없습니다
- 관리자가 한 명이고, 스타는 약 149개입니다
- Paperless-ngx 3.0 이후 오래된 설정은 HTTP 406을 만납니다
추천 대상
에이전트가 문서를 찾고, 태그를 달고, 정리하기를 원하며, 쓰기 호출은 승인 프롬프트 뒤에 둘 Paperless-ngx 사용자.
Paperless-NGX MCP Server 대안
Paperless-NGX MCP Server: 자주 묻는 질문
- Paperless-NGX MCP Server, 쓸 만한 가치가 있습니까?
- 설치할 가치가 있는 Paperless-ngx 서버입니다. 문서 정리 담당자의 하루 업무를 전부 처리할 만큼 범위가 넓고, 허락한다면 보관소를 지울 수 있을 만큼도 넓습니다. 평점은 5점 만점에 3.8점 입니다.
- Paperless-NGX MCP Server의 가격은 얼마입니까?
- 무료 오픈소스(ISC)입니다. Paperless-ngx 자체도 무료이며 자체 호스팅합니다.
- Paperless-NGX MCP Server의 단점은 무엇입니까?
- 일괄 삭제, 병합, 분할이 확인 플래그 없이 실행됩니다; 허용 목록을 설정하지 않으면 파일 경로 업로드에 제한이 없습니다; 관리자가 한 명이고, 스타는 약 149개입니다; Paperless-ngx 3.0 이후 오래된 설정은 HTTP 406을 만납니다.
- Paperless-NGX MCP Server에 적합한 사람은 누구입니까?
- 에이전트가 문서를 찾고, 태그를 달고, 정리하기를 원하며, 쓰기 호출은 승인 프롬프트 뒤에 둘 Paperless-ngx 사용자.
- 팀이나 프로덕션 환경에서 Paperless-NGX MCP Server의 비용은 얼마입니까?
- 무료입니다. Paperless-ngx는 자체 호스팅이므로 비용은 서버와 모델 토큰뿐입니다. 큰 결과 페이지와 base64 업로드가 컨텍스트를 부풀리는 주된 원인입니다.
- Paperless-NGX MCP Server에 회사 데이터를 맡겨도 안전합니까?
- API 토큰이 닿는 모든 것이며, 삭제도 포함됩니다. v2.0.0부터 HTTP 모드에서는 --no-auth를 설정하지 않는 한 요청마다 자체 Bearer 토큰이 있어야 합니다. 파일 경로 업로드는 PAPERLESS_MCP_UPLOAD_PATHS를 설정하지 않으면 어떤 로컬 파일이든 읽습니다. 공개된 GitHub 보안 권고는 없습니다.
- Paperless-NGX MCP Server의 가장 좋은 대안은 무엇입니까?
- 저희가 리뷰한 것 중 가장 가까운 대안은 Filesystem (reference server), MarkItDown MCP 및 Zotero MCP입니다.
답변 확인일: 2026년 10월 31일.