Paperless-NGX MCP Server

Paperless-NGX API 서버와 상호작용하기 위한 MCP(Model Context Protocol) 서버입니다. 이 서버는 Paperless-NGX 인스턴스에서 문서, 태그, 거래처, 문서 유형을 관리하기 위한 도구를 제공합니다.

빠른 시작

설치

MCP 구성 파일에 다음을 추가하세요:

// STDIO 모드(로컬 또는 CLI 사용에 권장)

"paperless": {
  "command": "npx",
  "args": [
    "-y",
    "@baruchiro/paperless-mcp@latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

// HTTP 모드(Docker 또는 원격 사용에 권장)

"paperless": {
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/baruchiro/paperless-mcp:latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

3. API 토큰을 가져옵니다:

   1. Paperless-NGX 인스턴스에 로그인합니다

   2. 오른쪽 상단에서 사용자 이름을 클릭합니다

   3. "내 프로필(My Profile)"을 선택합니다

   4. 원형 화살표 버튼을 클릭하여 새 토큰을 생성합니다

4. MCP 구성 파일의 자리 표시자를 바꿉니다:

   • http://your-paperless-instance:8000을(를) Paperless-NGX URL로

   • your-api-token을(를) 방금 생성한 토큰으로

   • https://your-public-domain.com을(를) 공개 Paperless-NGX URL로(선택 사항, PAPERLESS_URL로 대체됨)

환경 변수

이제 끝입니다! 이제 Claude에게 Paperless-NGX 문서 관리를 요청할 수 있습니다.

사용 예시

Claude에게 요청할 수 있는 작업의 예는 다음과 같습니다:

• "'Invoice' 태그가 있는 모든 문서를 보여줘"

• "'tax return'이 포함된 문서를 검색해 줘"

• "'Receipts'라는 새 태그를 색상 #FF0000으로 만들어 줘"

• "문서 #123을 다운로드해 줘"

• "모든 거래처를 나열해 줘"

• "'Bank Statement'라는 새 문서 유형을 만들어 줘"

Related MCP server: paperless-mcp

사용 가능한 도구

문서 작업

list_documents

간단한 필터로 문서의 페이지별 목록을 가져옵니다. 단순한 목록 작업에 사용하세요. 전체 텍스트 쿼리, 구조화된 사용자 정의 필드 필터링 또는 고급 Paperless 필터가 필요하면 query_documents를 사용하세요.

매개변수:

• page (선택 사항): 페이지 번호

• page_size (선택 사항): 페이지당 문서 수

• search (선택 사항): 간단한 Paperless 검색어

• correspondent (선택 사항): 거래처 ID

• document_type (선택 사항): 문서 유형 ID

• tag (선택 사항): 태그 ID

• storage_path (선택 사항): 저장 경로 ID

• created__date__gte (선택 사항): YYYY-MM-DD 이후(포함) 생성 날짜

• created__date__lte (선택 사항): YYYY-MM-DD 이전(포함) 생성 날짜

• ordering (선택 사항): Paperless 정렬 필드

• archive_serial_number (선택 사항): 아카이브 일련번호

• archive_serial_number__isnull (선택 사항): 아카이브 일련번호가 비어 있는지 여부

• custom_field_query (선택 사항): 원시 JSON으로 인코딩된 Paperless 사용자 정의 필드 쿼리 문자열

• custom_fields__icontains (선택 사항): 사용자 정의 필드 값에 대한 대소문자 구분 없는 부분 문자열 일치

list_documents({
  page: 1,
  page_size: 25
})

query_documents

표준 문서 쿼리 도구입니다. 전체 텍스트 쿼리, 간단한 Paperless 검색, 사용자 정의 필드 필터, 문서화된 /api/documents/ Paperless 쿼리 매개변수를 지원합니다.

매개변수:

• page (선택 사항): 페이지 번호

• page_size (선택 사항): 페이지당 문서 수

• ordering (선택 사항): Paperless 정렬 필드

• query (선택 사항): 전체 텍스트 쿼리 문자열

• search (선택 사항): 간단한 Paperless 검색어

• more_like_id (선택 사항): 이 문서 ID와 유사한 문서 찾기

• correspondent (선택 사항): 거래처 ID

• document_type (선택 사항): 문서 유형 ID

• tag (선택 사항): 태그 ID

• storage_path (선택 사항): 저장 경로 ID

• created__date__gte (선택 사항): YYYY-MM-DD 이후(포함) 생성 날짜

• created__date__lte (선택 사항): YYYY-MM-DD 이전(포함) 생성 날짜

• custom_field_query (선택 사항): [field_name_or_id, operator, value] 리프 또는 ["AND" | "OR", [clause1, clause2]] 그룹을 사용하는 구조화된 Paperless 사용자 정의 필드 쿼리

• paperless_filters (선택 사항): 키/값 쌍으로 전달되는 추가 문서화된 /api/documents/ Paperless 쿼리 매개변수

// Full-text query
query_documents({
  query: "invoice 2024"
})

// Simple search term
query_documents({
  search: "acme"
})

// Custom field exact match
query_documents({
  custom_field_query: ["Invoice Number", "exact", "12345"]
})

// Custom field empty
query_documents({
  custom_field_query: ["OR", [
    ["Invoice Number", "isnull", true],
    ["Invoice Number", "exact", ""]
  ]]
})

// Custom field missing
query_documents({
  custom_field_query: ["Invoice Number", "exists", false]
})

// Combined filters
query_documents({
  query: "invoice",
  tag: 5,
  created__date__gte: "2024-01-01",
  custom_field_query: ["Invoice Number", "exists", true]
})

// One documented Paperless filter that is not a first-class argument
query_documents({
  paperless_filters: {
    id__in: [101, 202, 303]
  }
})

get_document

ID로 특정 문서를 가져옵니다.

매개변수:

• id: 문서 ID

get_document({
  id: 123
})

search_documents

전체 텍스트 검색용으로 더 이상 사용되지 않는 호환성 래퍼입니다. 새 통합에서는 query_documents({ query: ... })를 사용하세요.

매개변수:

• query: 검색 쿼리 문자열

search_documents({
  query: "invoice 2024"
})

download_document

ID로 문서 파일을 다운로드합니다.

매개변수:

• id: 문서 ID

• original (선택 사항): true이면 아카이브 버전 대신 원본 파일을 다운로드합니다

download_document({
  id: 123,
  original: false
})

get_document_thumbnail

ID로 문서 썸네일(이미지 미리보기)을 가져옵니다. 썸네일을 base64로 인코딩된 WebP 이미지 리소스로 반환합니다.

매개변수:

• id: 문서 ID

get_document_thumbnail({
  id: 123
})

bulk_edit_documents

여러 문서에 대해 일괄 작업을 수행합니다.

매개변수:

• documents: 문서 ID 배열

• method: 다음 중 하나:

  • set_correspondent: 문서의 거래처 설정

  • set_document_type: 문서의 문서 유형 설정

  • set_storage_path: 문서의 저장 경로 설정

  • add_tag: 문서에 태그 추가

  • remove_tag: 문서에서 태그 제거

  • modify_tags: 여러 태그 추가 및/또는 제거

  • delete: 문서 삭제

  • reprocess: 문서 재처리

  • set_permissions: 문서 권한 설정

  • merge: 여러 문서 병합

  • split: 문서를 여러 문서로 분할

  • rotate: 문서 페이지 회전

  • delete_pages: 문서에서 특정 페이지 삭제

• 메서드에 따른 추가 매개변수:

  • correspondent: set_correspondent용 ID

  • document_type: set_document_type용 ID

  • storage_path: set_storage_path용 ID

  • tag: add_tag/remove_tag용 ID

  • add_tags: modify_tags용 태그 ID 배열

  • remove_tags: modify_tags용 태그 ID 배열

  • set_permissions: 보기/변경 사용자 및 그룹을 지정하는 set_permissions용 객체({"view": {"users": [], "groups": []}, "change": {...}}). 생략된 작업/목록은 변경되지 않습니다

  • owner: set_permissions용 사용자 ID(제거하려면 null). merge가 true가 아니면 owner를 생략하면 현재 소유자가 제거됩니다

  • merge: set_permissions용 부울 값 — true는 기존 권한에 추가하고 소유자를 유지하며, false(기본값)는 나열된 사용자/그룹을 대체합니다

  • metadata_document_id: 병합 시 메타데이터 소스를 지정하는 ID

  • delete_originals: merge/split용 부울 값

  • pages: split "[1,2-3,4,5-7]" 또는 delete_pages "[2,3,4]"용 문자열

  • degrees: rotate용 숫자(90, 180 또는 270)

예시:

// Add a tag to multiple documents
bulk_edit_documents({
  documents: [1, 2, 3],
  method: "add_tag",
  tag: 5
})

// Set correspondent and document type
bulk_edit_documents({
  documents: [4, 5],
  method: "set_correspondent",
  correspondent: 2
})

// Merge documents
bulk_edit_documents({
  documents: [6, 7, 8],
  method: "merge",
  metadata_document_id: 6,
  delete_originals: true
})

// Split document into parts
bulk_edit_documents({
  documents: [9],
  method: "split",
  pages: "[1-2,3-4,5]"
})

// Modify multiple tags at once
bulk_edit_documents({
  documents: [10, 11],
  method: "modify_tags",
  add_tags: [1, 2],
  remove_tags: [3, 4]
})

// Modify custom fields
bulk_edit_documents({
  documents: [12, 13],
  method: "modify_custom_fields",
  add_custom_fields: [
    { field: 2, value: "year" }
  ],
  remove_custom_fields: []
})

// Set an empty custom field value, e.g. a date field used as a pending marker
bulk_edit_documents({
  documents: [14],
  method: "modify_custom_fields",
  add_custom_fields: [
    { field: 9, value: "" }
  ],
  remove_custom_fields: []
})

post_document

Paperless-NGX에 새 문서를 업로드합니다.

두 가지 업로드 모드:

1. Base64 모드(기존 방식): file(base64로 인코딩된 콘텐츠) + filename을 제공합니다

2. 파일시스템 모드(효율적): file_path(서버의 절대 경로)를 제공합니다

보안 참고: file_path를 사용할 때는 PAPERLESS_MCP_UPLOAD_PATHS 환경 변수(허용 디렉터리의 콜론으로 구분된 목록)를 설정하여 업로드를 특정 위치로 제한하세요. 이 설정이 없으면 서버 파일시스템의 모든 파일을 업로드할 수 있습니다.

매개변수:

• file (선택 사항): Base64로 인코딩된 파일 콘텐츠. file 또는 file_path 중 하나가 필요합니다.

• file_path (선택 사항): 서버 파일시스템에 있는 파일의 절대 경로. file 또는 file_path 중 하나가 필요합니다.

• filename (선택 사항): 파일 이름. file과 함께 사용할 때 필수이며, file_path와 함께 사용할 때는 선택 사항입니다(경로에서 파생됨).

• title (선택 사항): 문서 제목

• created (선택 사항): 문서가 생성된 날짜/시간(예: "2024-01-19" 또는 "2024-01-19 06:15:00+02:00")

• correspondent (선택 사항): 거래처 ID

• document_type (선택 사항): 문서 유형 ID

• storage_path (선택 사항): 저장 경로 ID

• tags (선택 사항): 태그 ID 배열

• archive_serial_number (선택 사항): 아카이브 일련번호

• custom_fields (선택 사항): 사용자 정의 필드 ID 배열

파일 크기 제한: 두 모드 모두 100MB

// Base64 mode (traditional)
post_document({
  file: "base64_encoded_content",
  filename: "invoice.pdf",
  title: "January Invoice",
  created: "2024-01-19",
  correspondent: 1,
  document_type: 2,
  tags: [1, 3],
  archive_serial_number: "2024-001",
  custom_fields: [1, 2]
})

// Filesystem mode (more efficient for large files)
post_document({
  file_path: "/var/uploads/invoice.pdf",
  title: "January Invoice",
  correspondent: 1,
  document_type: 2,
  tags: [1, 3]
})

문서 메모

list_document_notes

문서에 첨부된 모든 메모를 나열합니다.

매개변수:

• id: 문서 ID

list_document_notes({
  id: 123
})

create_document_note

문서에 메모를 추가합니다. 문서의 전체 메모 목록을 반환합니다.

매개변수:

• id: 문서 ID

• note: 추가할 메모 텍스트

create_document_note({
  id: 123,
  note: "Invoice paid on 2026-06-30 from Commerzbank account."
})

delete_document_note

⚠️ 메모 ID로 문서에서 단일 메모를 삭제합니다. 이 작업은 되돌릴 수 없습니다.

매개변수:

• id: 문서 ID

• note_id: 삭제할 메모의 ID

• confirm: 이 파괴적 작업을 확인하려면 true여야 합니다

delete_document_note({
  id: 123,
  note_id: 5,
  confirm: true
})

태그 작업

list_tags

모든 태그를 가져옵니다.

list_tags()

create_tag

새 태그를 만듭니다.

매개변수:

• name: 태그 이름

• color (선택 사항): 16진수 색상 코드(예: "#ff0000")

• match (선택 사항): 일치시킬 텍스트 패턴

• matching_algorithm (선택 사항): 0에서 6 사이의 숫자: 0 - 없음 1 - 아무 단어 2 - 모든 단어 3 - 정확히 일치 4 - 정규 표현식 5 - 퍼지 단어 6 - 자동

create_tag({
  name: "Invoice",
  color: "#ff0000",
  match: "invoice",
  matching_algorithm: 5
})

거래처 작업

list_correspondents

모든 거래처를 가져옵니다.

list_correspondents()

create_correspondent

새 거래처를 만듭니다.

매개변수:

• name: 거래처 이름

• match (선택 사항): 일치시킬 텍스트 패턴

• matching_algorithm (선택 사항): 0에서 6 사이의 숫자: 0 - 없음 1 - 아무 단어 2 - 모든 단어 3 - 정확히 일치 4 - 정규 표현식 5 - 퍼지 단어 6 - 자동

create_correspondent({
  name: "ACME Corp",
  match: "ACME",
  matching_algorithm: 5
})

문서 유형 작업

list_document_types

모든 문서 유형을 가져옵니다.

list_document_types()

create_document_type

새 문서 유형을 만듭니다.

매개변수:

• name: 문서 유형 이름

• match (선택 사항): 일치시킬 텍스트 패턴

• matching_algorithm (선택 사항): 0과 6 사이의 숫자: 0 - 없음 1 - 단어 중 하나 2 - 모든 단어 3 - 정확히 일치 4 - 정규 표현식 5 - 퍼지 단어 6 - 자동

create_document_type({
  name: "Invoice",
  match: "invoice total amount due",
  matching_algorithm: 1
})

사용자 정의 필드 작업

list_custom_fields

모든 사용자 정의 필드를 가져옵니다.

list_custom_fields()

get_custom_field

ID로 특정 사용자 정의 필드를 가져옵니다.

매개변수:

• id: 사용자 정의 필드 ID

get_custom_field({
  id: 1
})

create_custom_field

새 사용자 정의 필드를 생성합니다.

매개변수:

• name: 사용자 정의 필드 이름

• data_type: "string", "url", "date", "boolean", "integer", "float", "monetary", "documentlink", "select" 중 하나

• extra_data (선택 사항): 선택 옵션 등 사용자 정의 필드에 대한 추가 데이터

create_custom_field({
  name: "Invoice Number",
  data_type: "string"
})

update_custom_field

기존 사용자 정의 필드를 업데이트합니다.

매개변수:

• id: 사용자 정의 필드 ID

• name (선택 사항): 새 사용자 정의 필드 이름

• data_type (선택 사항): 새 데이터 유형

• extra_data (선택 사항): 사용자 정의 필드에 대한 추가 데이터

update_custom_field({
  id: 1,
  name: "Updated Invoice Number",
  data_type: "string"
})

delete_custom_field

사용자 정의 필드를 삭제합니다.

매개변수:

• id: 사용자 정의 필드 ID

delete_custom_field({
  id: 1
})

bulk_edit_custom_fields

여러 사용자 정의 필드에 대해 일괄 작업을 수행합니다.

매개변수:

• custom_fields: 사용자 정의 필드 ID 배열

• operation: "delete" 중 하나

bulk_edit_custom_fields({
  custom_fields: [1, 2, 3],
  operation: "delete"
})

메일 작업

Paperless 메일 계정과 자동 이메일 수집을 구동하는 메일 규칙을 관리하기 위한 도구입니다. 계정 비밀번호/토큰은 절대 노출되지 않으며 모든 도구 응답에서 마스킹됩니다.

list_mail_accounts

메일 규칙을 만들 때 필요한 계정 ID를 선택할 수 있도록 메일 계정을 나열합니다. 비밀번호는 마스킹됩니다.

매개변수:

• page (선택 사항): 페이지 번호

• page_size (선택 사항): 페이지당 결과 수

list_mail_accounts()

get_mail_account

ID로 단일 메일 계정을 가져옵니다. 비밀번호/토큰 필드는 마스킹됩니다.

매개변수:

• id: 메일 계정 ID

get_mail_account({
  id: 1
})

process_mail_account

하나의 계정에 대해 Paperless 메일 처리를 수동으로 트리거합니다. 계정에서 활성화된 메일 규칙에 따라 일치하는 메일을 처리할 수 있습니다.

매개변수:

• id: 메일 계정 ID

process_mail_account({
  id: 1
})

list_mail_rules

선택적 페이지네이션으로 메일 규칙을 나열합니다.

매개변수:

• page (선택 사항): 페이지 번호

• page_size (선택 사항): 페이지당 결과 수

list_mail_rules()

get_mail_rule

ID로 단일 메일 규칙을 가져옵니다.

매개변수:

• id: 메일 규칙 ID

get_mail_rule({
  id: 1
})

create_mail_rule

메일 규칙을 생성합니다. 계정을 선택하려면 먼저 list_mail_accounts를 사용하세요.

필수 매개변수:

• name: 규칙 이름

• account: 메일 계정 ID

• folder: 검색할 IMAP 폴더 (예: "INBOX")

일반적인 선택 매개변수:

• enabled (기본값 true): 규칙이 활성화되어 있는지 여부

• filter_from / filter_to / filter_subject / filter_body: 수신 메일 일치

• maximum_age: 이 일수보다 최신 메일만 처리

• action: 1=삭제, 2=폴더로 이동, 3=읽음으로 표시, 4=플래그, 5=태그

• action_parameter: 선택한 작업의 대상 폴더/태그

• assign_title_from: 1=제목, 2=첨부 파일 이름, 3=할당 안 함

• assign_tags / assign_correspondent / assign_document_type: 적용할 메타데이터

• assign_correspondent_from: 1=없음, 2=메일 주소, 3=보낸 사람 이름, 4=assign_correspondent 사용

• attachment_type: 1=첨부 파일만, 2=인라인 포함 모든 파일

• consumption_scope: 1=첨부 파일만, 2=.eml 형식의 전체 메일, 3=둘 다

• pdf_layout: 0=시스템 기본값, 1=텍스트+HTML, 2=HTML+텍스트, 3=HTML만, 4=텍스트만

create_mail_rule({
  name: "Invoices",
  account: 1,
  folder: "INBOX",
  filter_subject: "invoice",
  action: 3,
  attachment_type: 1
})

update_mail_rule

기존 메일 규칙을 패치합니다. 제공한 필드만 변경됩니다.

매개변수:

• id: 메일 규칙 ID

• ...업데이트할 create_mail_rule 필드 중 원하는 항목

update_mail_rule({
  id: 1,
  enabled: false
})

delete_mail_rule

메일 규칙을 삭제합니다. 명시적인 확인 플래그가 필요합니다. 이 작업은 향후 메일 수집 동작을 변경하지만 기존 문서는 삭제하지 않습니다.

매개변수:

• id: 메일 규칙 ID

• confirm: 삭제를 확인하려면 true여야 합니다.

delete_mail_rule({
  id: 1,
  confirm: true
})

오류 처리

다음과 같은 경우 서버가 명확한 오류 메시지를 표시합니다:

• Paperless-NGX URL 또는 API 토큰이 올바르지 않은 경우

• Paperless-NGX 서버에 연결할 수 없는 경우

• 요청한 작업이 실패하는 경우

• 제공된 매개변수가 유효하지 않은 경우

테스트

단위 테스트

단위 테스트 스위트를 실행합니다 (외부 종속성 불필요):

npm test

E2E 테스트

E2E 스위트는 빈 Paperless-ngx 인스턴스를 부팅하고, 컴파일된 MCP 서버를 실행한 다음, tools/call 요청을 통해 결정적(deterministic) 직렬 시나리오를 구동합니다 — 태그, 발신처(correspondent), 문서 유형을 생성하고 PDF를 업로드한 다음 동일한 문서에 대해 list / get / search / download / thumbnail / bulk-edit을 실행합니다. MCP 외부의 LLM이나 Paperless REST 클라이언트는 사용하지 않습니다.

사전 요구 사항: Docker, Docker Compose 및 jq.

# 1. Build the MCP server
npm run build

# 2. Start Paperless-ngx
docker compose -f docker-compose.e2e.yml up -d

# 3. Wait for Paperless to be ready, then get a token
TOKEN=$(curl -s -X POST http://localhost:8000/api/token/ \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123"}' | jq -r '.token')

# 4. Start the MCP server
node build/index.js --http --port 3001 \
  --baseUrl http://localhost:8000 --token "$TOKEN" &
MCP_PID=$!

# 5. Run the E2E tests
MCP_URL=http://localhost:3001/mcp \
PAPERLESS_URL=http://localhost:8000 \
PAPERLESS_TOKEN="$TOKEN" \
npm run test:e2e

# 6. Cleanup
kill "$MCP_PID"
docker compose -f docker-compose.e2e.yml down -v

E2E 테스트는 모든 풀 리퀘스트와 main 브랜치 푸시 시 CI에서 자동으로 실행되며, build/index.js CLI와 게시된 Docker 이미지 모두를 대상으로 합니다.

개발

서버에 기여하거나 수정하고 싶으신가요? 알아야 할 사항은 다음과 같습니다:

1. 저장소를 클론합니다.

2. 종속성을 설치합니다:

npm install

3. server.js를 수정합니다.

4. 로컬에서 테스트합니다:

node server.js http://localhost:8000 your-test-token

서버는 다음으로 구축되었습니다:

• litemcp: MCP 서버 구축을 위한 TypeScript 프레임워크

• zod: TypeScript 우선 스키마 검증

API 문서

이 MCP 서버는 Paperless-NGX REST API의 엔드포인트를 구현합니다. 기본 API에 대한 자세한 내용은 공식 문서를 참조하세요.

MCP 서버 실행

MCP 서버는 두 가지 모드로 실행할 수 있습니다:

1. stdio (기본값)

이것은 기본 모드입니다. 서버는 stdio를 통해 통신하며, CLI 및 직접 통합에 적합합니다.

npm run start -- <baseUrl> <token>

2. HTTP (Streamable HTTP Transport)

서버를 HTTP 서비스로 실행하려면 --http 플래그를 사용하세요. --port로 포트를 지정할 수도 있습니다 (기본값: 3000). 이 모드에서는 Express가 설치되어 있어야 합니다 (종속성으로 포함되어 있습니다).

npm run start -- <baseUrl> <token> --http --port 3000

• MCP API는 지정된 포트의 POST /mcp에서 사용할 수 있습니다.

• 각 요청은 StreamableHTTPServerTransport 패턴에 따라 상태 비저장(stateless) 방식으로 처리됩니다.

• /mcp에 대한 GET 및 DELETE 요청은 405 Method Not Allowed를 반환합니다.

요청별 API 토큰 (HTTP/Docker 모드)

HTTP 모드에서 클라이언트는 표준 Authorization 헤더를 통해 Paperless-NGX API 토큰을 제공하여 인증합니다:

Authorization: Bearer <paperless-ngx-api-token>

토큰은 Paperless-NGX로 직접 전달되므로 각 클라이언트의 Paperless 권한이 종단 간(end-to-end) 적용됩니다. 이를 통해 단일 서버 인스턴스가 각자 자신의 토큰을 가진 여러 사용자에게 서비스를 제공할 수 있습니다. 동일한 동작이 /mcp 및 /sse 엔드포인트 모두에 적용됩니다.

⚠️ v2.0.0의 주요 변경 사항 — HTTP 모드는 이제 기본적으로 인증됩니다.

이전에는 Authorization 헤더가 없는 요청이 서버에 구성된 PAPERLESS_API_KEY로 자동 대체되어, 포트에 접근할 수 있는 모든 사람에게 HTTP 엔드포인트가 열려 있었습니다. v2.0.0부터는 Bearer 토큰이 없는 요청은 401 Unauthorized로 거부됩니다. 서버 토큰은 --no-auth로 명시적으로 선택하지 않는 한 인증되지 않은 요청에 절대 사용되지 않습니다.

v1.x에서 마이그레이션: 토큰을 보내지 않는 클라이언트와 단일 공유 PAPERLESS_API_KEY를 사용하는 이전 폴백(fallback) 방식에 의존했다면 두 가지 옵션이 있습니다:

1. 권장: 각 클라이언트가 Authorization: Bearer <paperless-token>을 보내도록 합니다.

2. 이전 동작 복원 (신뢰할 수 있는 로컬 네트워크 전용): --no-auth 플래그로 서버를 시작합니다. 예를 들어 Docker command/args 또는 CLI 호출에 추가하세요. 이 경우 서버 토큰(PAPERLESS_API_KEY 또는 --token)이 구성되어 있어야 합니다.

MCP 서버는 Docker 및 Docker Compose를 사용하여 배포할 수 있습니다. Docker 이미지는 포트 3000에서 SSE(Server-Sent Events) 지원과 함께 HTTP 모드로 자동 실행됩니다.

Docker Compose 구성

docker-compose.yml 파일을 생성합니다:

services:
  paperless-mcp:
    container_name: paperless-mcp
    image: ghcr.io/baruchiro/paperless-mcp:latest
    environment:
      - PAPERLESS_URL=http://your-paperless-ngx-server:8000
      - PAPERLESS_API_KEY=your-paperless-api-key
      - PAPERLESS_PUBLIC_URL=https://paperless-ngx.yourpublicurl.com
    ports:
      - "3000:3000"
    restart: unless-stopped

그런 다음 실행합니다:

docker-compose up -d

Continue VS Code 확장과 함께 사용

Continue VS Code 확장을 사용하는 경우 SSE를 통해 Docker화된 MCP 서버를 사용하도록 구성할 수 있습니다.

작업 공간 루트에 .continue/mcpServers/paperless-mcp.yaml을 생성하거나 편집합니다:

name: Paperless
version: 0.0.1
schema: v1
mcpServers:
  - name: Paperless
    type: sse
    url: http://localhost:3000/sse

참고:

• 원격 서버에서 실행하는 경우 localhost를 Docker 호스트의 IP 주소 또는 호스트 이름으로 바꾸세요.

• Docker 컨테이너는 환경 변수를 통해 인증을 처리하므로 Continue 구성에 자격 증명이 필요하지 않습니다.

• SSE 엔드포인트는 구성된 포트(기본값: 3000)의 /sse에서 사용할 수 있습니다.

크레딧

이 프로젝트는 nloui/paperless-mcp의 포크입니다. 원저자의 작업에 깊이 감사드립니다. 기여와 개선 사항은 업스트림으로 반환될 수 있습니다.

디버깅

VS Code에서 MCP 서버를 디버깅하려면 다음 실행 구성을 사용하세요:

{
    "type": "node",
    "request": "launch",
    "name": "Debug Paperless MCP (HTTP, ts-node ESM)",
    "program": "${workspaceFolder}/node_modules/ts-node/dist/bin.js",
    "args": [
        "--esm",
        "src/index.ts",
        "--http",
        "--baseUrl",
        "http://your-paperless-instance:8000",
        "--token",
        "your-api-token",
        "--port",
        "3002"
    ],
    "env": {
        "NODE_OPTIONS": "--loader ts-node/esm",
    },
    "console": "integratedTerminal",
    "skipFiles": [
        "<node_internals>/**"
    ]
}

중요: 디버깅 전에 src/index.ts의 다음 줄(약 175행)의 주석을 해제하세요:

// await new Promise((resolve) => setTimeout(resolve, 1000000));

이렇게 하면 서버가 즉시 종료되지 않으며 중단점을 설정하고 코드를 디버깅할 수 있습니다.