Nextcloud MCP 서버

AI 어시스턴트를 Nextcloud 인스턴스에 연결하는 프로덕션급 MCP 서버입니다.

Claude, GPT, Gemini와 같은 거대 언어 모델이 보안 API를 통해 Nextcloud 데이터와 상호 작용할 수 있도록 합니다. 자연어 대화를 통해 메모 작성, 캘린더 관리, 연락처 정리, 파일 작업 등을 수행하세요.

이 서버는 Claude Code 및 IDE와 같은 외부 MCP 클라이언트를 위해 설계된 전용 독립형 MCP 서버입니다. Nextcloud(Docker, VM, Kubernetes 또는 로컬)와 독립적으로 실행되며 Nextcloud 앱 전반에 걸쳐 심층적인 CRUD 작업을 제공합니다.

[!NOTE] Nextcloud 내부의 AI 기능을 찾고 계신가요? Nextcloud는 또한 Context Agent를 제공하며, 이는 Assistant 앱을 구동하고 Nextcloud 내부에서 ExApp으로 실행됩니다. 사용 사례에 대한 자세한 비교는 docs/comparison-context-agent.md를 참조하세요.

빠른 시작 (Docker)

시맨틱 검색을 포함한 모든 기능을 사용하려면 Docker로 실행하세요:

# 1. Create a minimal configuration
cat > .env << EOF
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_username
NEXTCLOUD_PASSWORD=your_app_password
EOF

# 2. Start the server
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

# 3. Test the connection
curl http://127.0.0.1:8000/health/ready

# 4. Connect to the endpoint
http://127.0.0.1:8000/sse

# Or with --transport streamable-http
http://127.0.0.1:8000/mcp

Docker Compose 프로필 (개발/테스트용):

docker compose --profile single-user up -d       # Port 8000
docker compose --profile multi-user-basic up -d   # Port 8003
docker compose --profile oauth up -d              # Port 8001
docker compose --profile login-flow up -d         # Port 8004

다음 단계:

• MCP 클라이언트(Claude Desktop, IDE, mcp dev 등) 연결

• 다른 배포 옵션(로컬, Kubernetes)은 docs/installation.md 참조

Related MCP server: Nextcloud MCP Server

주요 기능

• 90개 이상의 MCP 도구 - 8개의 Nextcloud 앱에 걸친 포괄적인 API 지원

• MCP 리소스 - Nextcloud 데이터를 탐색하기 위한 구조화된 데이터 URI

• 시맨틱 검색 (실험적) - 메모, 파일, 뉴스 항목 및 Deck 카드를 위한 선택적 벡터 기반 검색 (Qdrant + Ollama 필요)

• 문서 처리 - 진행 상황 알림과 함께 PDF, DOCX, 이미지에서 OCR 및 텍스트 추출

• 유연한 배포 - Docker, Kubernetes(Helm), VM 또는 로컬 설치

• 프로덕션급 인증 - 앱 비밀번호를 사용한 기본 인증(권장) 또는 OAuth2/OIDC(실험적)

• 다중 전송 - SSE, HTTP 및 스트리밍 가능한 HTTP 지원

지원되는 앱

다른 Nextcloud 앱 지원을 원하시나요? 이슈를 열거나 풀 리퀘스트를 제출해 주세요!

인증

[!IMPORTANT] OAuth2/OIDC는 실험적 기능이며 user_oidc 앱에 수동 패치가 필요합니다:

• 필수 패치: Bearer 토큰 지원 (이슈 #1221)

• 영향: 패치가 없으면 대부분의 앱별 API가 401 오류와 함께 실패함

• 권장 사항: 업스트림 패치가 병합될 때까지 프로덕션 환경에서는 기본 인증을 사용하세요

패치 상태 및 해결 방법은 docs/oauth-upstream-status.md를 참조하세요.

권장: 앱별 비밀번호를 사용하는 기본 인증은 안전하고 프로덕션 준비가 완료된 인증을 제공합니다. 설정 세부 정보 및 OAuth 구성은 docs/authentication.md를 참조하세요.

인증 모드

이 서버는 네 가지 인증 모드를 지원합니다:

단일 사용자 (BasicAuth):

• 모든 MCP 클라이언트가 공유하는 하나의 자격 증명 세트

• 간단한 설정: 환경 변수에 사용자 이름 + 앱 비밀번호 입력

• 모든 클라이언트가 동일한 사용자로 Nextcloud에 액세스

• 용도: 개인용, 개발용, 단일 사용자 배포

다중 사용자 (BasicAuth 패스스루):

• MCP 클라이언트가 Authorization 헤더를 통해 자격 증명 전송

• 서버가 Nextcloud로 패스스루 (기본적으로 상태 비저장)

• 백그라운드 작업을 위한 선택적 오프라인 액세스 (ENABLE_MULTI_USER_BASIC_AUTH=true)

• 용도: OAuth 인프라가 없는 다중 사용자 설정

다중 사용자 (OAuth):

• 각 MCP 클라이언트가 자신의 Nextcloud 계정으로 별도 인증

• 사용자별 범위 및 권한 (클라이언트는 권한이 있는 도구만 볼 수 있음)

• 더 안전함: 토큰 만료, 자격 증명이 서버와 공유되지 않음

• 용도: 팀, 다중 사용자 배포, 여러 사용자가 있는 프로덕션 환경

• 요구 사항: user_oidc 앱 패치 (실험적)

다중 사용자 (로그인 흐름 v2):

• Nextcloud의 기본 로그인 흐름 v2를 사용하여 사용자별 앱 비밀번호 획득

• OAuth 패치 불필요 — 기본 Nextcloud와 작동

• 각 사용자가 브라우저를 통해 인증, 서버가 앱 비밀번호 관리

• 용도: OAuth 인프라가 없는 다중 사용자 배포 (ENABLE_LOGIN_FLOW=true)

• 실험적: 자세한 내용은 ADR-022 참조

자세한 설정 지침은 docs/authentication.md를 참조하세요.

시맨틱 검색

이 서버는 MCP 클라이언트가 키워드뿐만 아니라 의미를 기반으로 Nextcloud에서 정보를 찾을 수 있도록 하는 실험적인 RAG 파이프라인인 시맨틱 검색을 제공합니다. "머신 러닝"이라는 단어가 정확히 나타날 때만 일치시키는 대신, "신경망", "AI 모델", "딥 러닝"이 의미적으로 관련된 개념임을 이해합니다.

예시:

• 키워드 검색: "자동차"를 쿼리하면 "자동차"가 포함된 메모만 찾음

• 시맨틱 검색: "자동차"를 쿼리하면 "자동차", "차량", "세단", "교통"에 관한 메모도 찾음

이를 통해 자연어 쿼리가 가능하며 Nextcloud 메모 전반에서 관련 콘텐츠를 발견하는 데 도움이 됩니다.

[!NOTE] 시맨틱 검색은 실험적이며 선택 사항입니다:

• 기본적으로 비활성화됨 (ENABLE_SEMANTIC_SEARCH=false)

• 현재 메모 앱만 지원 (다중 앱 지원 예정)

• 추가 인프라 필요: 벡터 데이터베이스 + 임베딩 서비스

• 답변 생성 (nc_semantic_search_answer)은 MCP 클라이언트 샘플링 지원 필요

아키텍처 세부 정보는 docs/semantic-search-architecture.md를, 설정 지침은 docs/configuration.md를 참조하세요.

문서

시작하기

• 설치 - Docker, Kubernetes, 로컬 또는 VM 배포

• 구성 - 환경 변수 및 고급 옵션

• 인증 - 기본 인증 vs OAuth2/OIDC 설정

• 서버 실행 - 시작, 관리 및 문제 해결

기능

• 앱 문서 - 메모, 캘린더, 연락처, WebDAV, Deck, 요리책, 테이블

• 문서 처리 - OCR 및 텍스트 추출 설정

• 시맨틱 검색 아키텍처 - 실험적 벡터 검색 (메모, 파일, 뉴스 항목, Deck 카드; 선택 사항)

• 벡터 동기화 UI 가이드 - 시맨틱 검색 시각화 및 테스트를 위한 브라우저 인터페이스

고급 주제

• OAuth 아키텍처 - OAuth 작동 방식 (실험적)

• OAuth 빠른 시작 - 5분 OAuth 설정

• OAuth 설정 가이드 - 상세 OAuth 구성

• 문제 해결 - 일반적인 문제 및 해결 방법

• Context Agent와의 비교 - 각 접근 방식을 사용할 때

예시

메모 작성

AI: "Create a note called 'Meeting Notes' with today's agenda"
→ Uses nc_notes_create_note tool

레시피 가져오기

AI: "Import the recipe from https://www.example.com/recipe/chocolate-cake"
→ Uses nc_cookbook_import_recipe tool with schema.org metadata extraction

회의 일정 잡기

AI: "Schedule a team meeting for next Tuesday at 2pm"
→ Uses nc_calendar_create_event tool

파일 관리

AI: "Create a folder called 'Project X' and move all PDFs there"
→ Uses nc_webdav_create_directory and nc_webdav_move tools

시맨틱 검색 (실험적, 선택 사항)

AI: "Find notes related to machine learning concepts"
→ Uses nc_semantic_search to find semantically similar notes (requires Qdrant + Ollama setup)

참고: 인용문이 포함된 AI 생성 답변을 보려면 nc_semantic_search_answer를 사용하세요 (샘플링 지원이 있는 MCP 클라이언트 필요).

기여

기여를 환영합니다!

• 버그 보고 또는 기능 요청: GitHub Issues

• 개선 사항 제출: Pull Requests

• 개발 가이드라인: CLAUDE.md

보안

이 프로젝트는 보안을 중요하게 생각합니다:

• 앱별 비밀번호를 사용하는 프로덕션급 기본 인증

• OAuth2/OIDC 지원 (실험적, 업스트림 패치 필요)

• 사용자별 액세스 토큰

• OAuth 모드에서 자격 증명 저장 안 함

• 정기적인 보안 평가

보안 문제를 발견하셨나요? 유지 관리자에게 비공개로 보고해 주세요.

라이선스

이 프로젝트는 AGPL-3.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE를 참조하세요.

스타 기록

참조

• Model Context Protocol

• MCP Python SDK

• Nextcloud