mcp-paperless-ngx

REST API 버전 10을 기준으로 빌드되었으며, 세 가지 차별점이 있습니다:

• 완전한 커버리지. 문서화된 92개 엔드포인트 각각은 도구로 노출되거나 src/tools/coverage.ts에 제외 사유와 함께 명시되어 있습니다. 테스트가 이를 강제하므로, Paperless 릴리스에서 엔드포인트가 추가되면 조용히 미지원으로 남는 대신 CI가 실패합니다.

• 토큰 절약. Paperless 문서에는 전체 OCR 텍스트가 포함됩니다. 단순한 래퍼는 이를 기본으로 반환하며, 한 번의 검색으로 모델의 컨텍스트가 소진될 수 있습니다. 여기서는 목록 결과가 ?fields=를 통해 서버 측에서 잘리고, 텍스트는 자체 페이지네이션 도구 뒤에 있으며, 어떤 목록 엔드포인트도 원시 API 응답을 그대로 전달하지 않습니다 — 테스트가 이를 강제합니다. 컨텍스트 비용 참조.

• 범위 제한. 99개의 도구는 모델의 도구 목록을 압도할 수 있습니다. 툴셋을 사용하면 특정 클라이언트가 필요한 것만 노출할 수 있으며, --read-only는 모든 쓰기 경로를 완전히 제거합니다.

Paperless-ngx 2.x는 지원되지 않습니다: API 버전 10은 이 서버가 존재를 전제로 하는 엔드포인트(중첩 태그, 문서 버전, share_link_bundles, 분할 PDF 작업)를 도입했습니다.

빠른 시작

npx -y mcp-paperless-ngx --check   # verify connectivity, then exit

Claude Code

claude mcp add paperless --scope user \
  --env PAPERLESS_URL=https://paperless.example.com \
  --env PAPERLESS_TOKEN=your-api-token \
  -- npx -y mcp-paperless-ngx

Claude Desktop, Cursor, Cline 및 기타 MCP 클라이언트

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["-y", "mcp-paperless-ngx"],
      "env": {
        "PAPERLESS_URL": "https://paperless.example.com",
        "PAPERLESS_TOKEN": "your-api-token"
      }
    }
  }
}

API 토큰 얻기

Paperless 웹 UI → 사용자 이름(오른쪽 상단) → 내 프로필 → API 토큰 필드 옆의 원형 화살표 버튼.

Related MCP server: paperlessngx-mcp

구성

CLI 플래그 --url, --token, --public-url, --toolsets 및 --read-only는 환경 변수를 재정의합니다. --check는 연결을 확인하고, --list-tools는 활성화된 도구를 출력합니다.

툴셋

mail과 admin은 대부분의 세션에서 필요하지 않고 추가 도구마다 모든 요청에서 컨텍스트를 소모하므로 기본적으로 꺼져 있습니다. 명시적으로 활성화하세요:

PAPERLESS_TOOLSETS=documents,metadata,system,mail
PAPERLESS_TOOLSETS=all

컨텍스트 비용

언어 모델용 API를 래핑하면 API 자체에는 없는 비용이 발생합니다: 모델이 보는 모든 것은 모든 요청에서 비용이 청구됩니다. 문제가 되는 두 지점과 이 서버가 이를 처리하는 방법입니다.

응답. Paperless에서 비용이 많이 드는 세 가지 형태가 있으며 실수로 반환하기 쉽습니다:

도구 정의. 더 크고 덜 명확한 비용입니다: 이름, 설명 및 JSON 스키마가 도구가 호출되는지 여부와 관계없이 모든 요청에 포함됩니다.

이를 무료로 만들 방법은 없습니다 — 모델이 추측 없이 사용할 수 있는 도구의 대가입니다. 그러나 신중할 가치가 있습니다: 세션이 문서 검색과 분류만 수행한다면 PAPERLESS_TOOLSETS=documents,metadata를 실행하는 것이 어떤 응답 트리밍보다 더 많은 컨텍스트를 절약합니다.

안전

이 서버는 파괴적 작업을 노출합니다. 문서 관리자가 그런 기능 없이는 관리자라고 할 수 없기 때문입니다. 언제 적절한지 추측하지 않습니다 — 그 판단은 클라이언트와 사용자의 몫입니다. 대신 다음을 수행합니다:

• 파괴적 도구는 destructiveHint: true로 주석 처리되어 MCP 클라이언트가 확인을 요구할 수 있습니다.

• 도구 설명은 되돌릴 수 없는 작업(empty_trash, delete_custom_field, delete_originals)을 명확히 명시하고 호출 전 확인을 요청합니다.

• --read-only는 호출 시 거부하는 대신 모든 쓰기 도구를 목록에서 제거합니다.

• 일괄 엔드포인트는 "이 필터와 일치하는 모든 항목에 적용" 모드를 지원합니다. 이 서버는 이를 노출하지 않습니다: 일괄 도구는 명시적 ID 목록을 받으므로 잘못된 필터가 전체 아카이브에 조용히 영향을 줄 수 없습니다.

• create_share_link는 공개적으로 접근 가능한 URL을 생성합니다. 설명에 이를 명시하며, audit_sharing 프롬프트는 이미 노출된 항목을 검토하기 위해 존재합니다.

자격 증명 관련 엔드포인트(토큰 생성, TOTP 등록, 타인의 2차 인증 비활성화)는 의도적으로 노출되지 않습니다. 전체 목록과 근거는 EXCLUDED_ENDPOINTS를 참조하세요.

프롬프트

MCP 프롬프트를 지원하는 클라이언트에서 슬래시 명령으로 등록됩니다:

테스트

서로 다른 문제를 잡아내는 세 계층:

npm test                                        # logic — no network
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/smoke-test.mjs                   # all 55 read-only tools, live
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/write-test.mjs                   # writes, live — see the warning

npm test는 이 서버 자체의 추론을 확인합니다: 엔드포인트 커버리지, 스키마에 대한 열거형 값, 어떤 목록 도구도 원시 API 객체를 누출하지 않는지, 읽기 전용 모드가 실제로 쓰기를 제거하는지.

smoke-test.mjs는 Paperless에 대해 가정하는 사항을 확인합니다. 실제 인스턴스에 대해 모든 읽기 전용 도구를 호출하고, ID를 하드코딩하는 대신 목록 호출에서 해결하며, 비용이 많이 드는 도구가 계속 보이도록 응답 크기를 출력합니다. 아무것도 쓰지 않습니다.

write-test.mjs는 나머지를 다룹니다: 업로드 및 소비, 모든 필드 유형 업데이트, 메모, 일괄 태그 편집, 공유 링크, 회전 및 휴지통 왕복.

자체적으로 생성한 객체만 건드립니다. 만드는 모든 것은 zz-mcp-test 접두사로 이름이 지정되고 마지막에 다시 삭제되며, 업로드하지 않은 문서는 절대 수정하지 않습니다. 실행이 중단되면 해당 접두사가 있는 잔여물은 삭제해도 안전합니다. 테스트 인스턴스가 있다면 사용하는 것이 좋습니다.

Paperless 최신 버전 유지

PAPERLESS_URL=… PAPERLESS_TOKEN=… node scripts/sync-schema.mjs
npm test

sync-schema.mjs는 자체 인스턴스의 OpenAPI 문서에서 schema/endpoints.json을 재생성합니다. 그런 다음 테스트 스위트는 노출되지도 명시적으로 제외되지도 않은 엔드포인트를 보고합니다. 이것이 전체 유지 관리 루프입니다: 더 새로운 Paperless를 가리키면 테스트가 무엇이 변경되었는지 알려줍니다.

개발

npm install
npm start          # run from source
npm run build      # compile to build/
npm test           # unit tests + coverage checks
npm run inspect    # build, then open the MCP inspector

선행 작업

Paperless용 MCP 서버는 이미 여러 개 존재하며, 가장 주목할 만한 것으로는 cubinet-code/paperless-ngx-mcp가 있고, 또한 nloui/paperless-mcp와 barryw/PaperlessMCP도 있습니다. 이들은 2.x API를 대상으로 합니다. Paperless-ngx 2.x를 실행 중이라면 그중 하나를 사용하세요. 이 프로젝트는 3.x를 전제로 합니다.

라이선스

MIT. LICENSE를 참조하세요.