Obsidian MCP 도구 서버

이 프로젝트는 Obsidian 볼트와 상호 작용하기 위한 도구를 제공하는 MCP(Model Context Protocol) 서버를 제공합니다.

목차

• 특징
• 설치
• 구성
• 수동 실행(테스트/디버깅용)
• 클라이언트 구성(예: Claude Desktop)
• 사용 가능한 MCP 도구
• 로드맵
• 자주 묻는 질문(FAQ)
• 기여를 환영합니다!

특징

MCP 클라이언트(AI 어시스턴트 등)가 다음을 수행할 수 있습니다.

• 노트 읽기 및 쓰기
• 노트 메타데이터 관리(프론트매터)
• 메모 및 폴더 목록
• 콘텐츠 또는 메타데이터로 노트 검색
• 일일 노트 관리
• 나가는 링크, 백링크 및 태그를 얻으세요

설치

1. 저장소를 복제합니다 (아직 복제하지 않았다면):지엑스피1
2. 프로젝트 디렉토리로 이동합니다 .
   cd /path/to/your/OMCP
3. Python 가상 환경을 만듭니다 (종속성 충돌을 방지하기 위해 권장):
   python -m venv .venv
4. 가상 환경 활성화 :
   • Windows PowerShell에서:
     .venv\Scripts\Activate.ps1
   • Linux/macOS의 경우:GXP5(이제 터미널 프롬프트의 시작 부분에 (.venv) 가 표시되어야 합니다)
5. 패키지와 종속성을 설치하세요 .
   pip install .

구성

이 서버는 환경 변수를 사용하여 구성되며, 프로젝트 루트에 있는 .env 파일을 사용하여 편리하게 관리할 수 있습니다.

1. 예제 파일을 복사하세요:
   # From the project root directory (OMCP/) cp .env.example .env
   (Windows에서는 copy .env.example .env 사용할 수 있습니다.)
2. .env 파일 편집: 텍스트 편집기에서 새로 만든 .env 파일을 엽니다.
3. OMCP_VAULT_PATH 설정: 필수 변수는 이것뿐입니다. Obsidian 볼트의 절대 경로 로 업데이트하세요. Windows에서도 경로에 슬래시( / )를 사용하세요.
   OMCP_VAULT_PATH="/path/to/your/Obsidian/Vault"
4. 선택 설정 검토: 필요한 경우 일일 메모, 서버 포트 또는 백업 디렉터리에 대한 다른 OMCP_ 변수를 조정합니다. 자세한 내용은 파일의 주석을 참조하십시오.

(또는 .env 파일을 사용하는 대신 이를 실제 시스템 환경 변수로 설정할 수 있습니다. 둘 다 설정되어 있는 경우 서버는 .env 파일보다 시스템 환경 변수를 우선시합니다.)

수동 실행(테스트/디버깅용)

Claude Desktop과 같은 클라이언트 애플리케이션은 아래 설명된 구성을 사용하여 서버를 자동으로 시작하지만, 직접 테스트나 디버깅을 위해 터미널에서 수동으로 서버를 실행할 수도 있습니다.

1. 구성이 완료되었는지 확인하세요. 구성 섹션에 설명된 대로 .env 파일을 만들고 구성했는지 확인하세요.
2. 가상 환경 활성화:
   # If not already active .venv\Scripts\Activate.ps1
   (Linux/macOS에서는 source .venv/bin/activate 사용하세요)
3. 서버 스크립트를 실행합니다.
   (.venv) ...> python obsidian_mcp_server/main.py

서버가 시작되고 수신 대기 중인 주소(예: http://127.0.0.1:8001 )가 출력됩니다. 테스트가 끝나면 일반적으로 Ctrl+C 눌러 서버를 중지합니다.

참고: 이 서버를 Claude Desktop이나 유사한 런처와 함께 사용하려면 이와 같이 수동으로 실행 하지 마세요 . 대신 클라이언트 애플리케이션을 구성하면(다음 섹션 참조) 서버 프로세스의 시작 및 중지가 자동으로 처리됩니다.

클라이언트 구성(예: Claude Desktop)

많은 MCP 클라이언트(예: Claude Desktop)는 서버 프로세스를 직접 실행할 수 있습니다. 이러한 클라이언트를 구성하려면 일반적으로 JSON 구성 파일(예: macOS/Linux에서는 claude_desktop_config.json , Windows에서는 AppData 에서 동일한 경로를 찾으세요)을 편집해야 합니다.

⚠️ 중요한 JSON 서식 규칙:

1. JSON 파일은 주석을 지원 하지 않습니다 ( // 또는 /* */ 주석을 제거하세요)
2. 모든 문자열은 큰따옴표( " )로 적절히 따옴표로 묶어야 합니다.
3. Windows 경로는 이스케이프된 백슬래시( \\ )를 사용해야 합니다.
4. JSON 검증기(예: jsonlint.com )를 사용하여 구문을 확인하세요.

다음은 클라이언트의 JSON 구성에서 mcpServers 키에 추가할 항목의 예입니다.

주요 포인트:

• 경로를 시스템에 관련된 절대 경로 로 바꾸세요.
• command 및 args 필드의 Windows 경로:
  • 경로 구분 기호에는 이중 백슬래시( \\ )를 사용합니다.
  • Python 실행 파일에 .exe 확장자를 포함합니다.
• env 블록의 Windows 경로:
  • 더 나은 호환성을 위해 슬래시( / )를 사용하세요.
  • .exe 확장자를 포함하지 마십시오.
• command 경로는 생성한 .venv내부의 python.exe 실행 파일을 가리켜 야 합니다 .
• args 경로는 obsidian_mcp_server 하위 폴더 내의 main.py 파일을 가리켜 야 합니다 .
• env 블록을 사용하는 것은 서버가 볼트 경로를 찾을 수 있도록 보장하는 가장 안정적인 방법입니다.
• JSON 구성을 수정한 후에 는 클라이언트 애플리케이션을 다시 시작 해야 합니다.

피해야 할 일반적인 함정:

1. Windows 경로에 단일 백슬래시를 사용하지 마십시오.
2. JSON에 주석을 포함하지 마세요
3. Windows 경로에서 백슬래시를 이스케이프하는 것을 잊지 마세요.
4. 동일한 경로에 정슬래시와 역슬래시를 섞어 쓰지 마세요.
5. 모든 문자열을 올바르게 인용하는 것을 잊지 마세요.

사용 가능한 MCP 도구

• list_folders
• list_notes
• get_note_content
• get_note_metadata
• get_outgoing_links
• get_backlinks
• get_all_tags
• search_notes_content
• search_notes_metadata
• search_folders
• create_note
• edit_note
• append_to_note
• update_note_metadata
• delete_note
• get_daily_note_path
• create_daily_note
• append_to_daily_note

로드맵

이 프로젝트는 현재 활발하게 개발 중입니다. 계획된 기능은 다음과 같습니다.

v1.x (단기)

• 템플릿 기반 노트 생성:
  • 템플릿 디렉토리( OMCP_TEMPLATE_DIR )를 구성합니다.
  • create_note_from_template 도구를 구현합니다(템플릿 이름, 대상 경로, 선택적 메타데이터 사용).
  • 템플릿 생성을 위한 테스트를 추가합니다.
• 폴더 생성:
  • create_folder 유틸리티 함수를 구현합니다.
  • create_folder MCP 도구를 구현합니다.
  • 폴더 생성에 대한 테스트를 추가합니다.

v1.y (중기/향후 개선 사항)

• 템플릿에서의 변수 대체(예: {{DATE}} ).
• list_templates 도구.
• 고급 노트 업데이트 도구(예: append_to_note_by_metadata ).
• 포괄적인 볼트 계층 구조를 보기 위한 list_vault_structure 도구입니다.
• 포괄적인 테스트 검토 및 확장.

v2.x+ (잠재적 아이디어/장기)

• 조직 도구:
  • move_item(source, destination) (초기 버전에서는 링크가 업데이트되지 않을 수 있음).
  • rename_item(path, new_name) (초기 버전에서는 링크가 업데이트되지 않을 수 있음).
• 콘텐츠 조작 도구:
  • replace_text_in_note(path, old, new, count) .
  • prepend_to_note(path, content) .
  • append_to_section(path, heading, content) (신뢰할 수 있는 제목 구문 분석이 필요합니다).
• 쿼리 도구:
  • get_local_graph(path) (나가는 링크/백링크를 결합합니다).
  • search_notes_by_metadata_field(key, value) .
• 플러그인 통합 도구:
  • 데이터뷰 통합:
    • execute_dataview_query(query_type, query) - Dataview 쿼리를 실행하고 구조화된 결과를 얻습니다.
    • search_by_dataview_field(field, value) - Dataview 필드로 노트 검색
  • 업무 관리:
    • query_tasks(status, due_date, tags) - 볼트 전체에서 작업 검색 및 필터링
  • 칸반 통합:
    • get_kanban_data(board_path) - 구조화된 칸반 보드 데이터 가져오기
  • 캘린더 통합:
    • get_calendar_events(start_date, end_date) - 캘린더 이벤트 및 작업 쿼리

자주 묻는 질문(FAQ)

구성 문제

질문: 서버에서 볼트를 찾을 수 없습니다. 무엇이 문제인가요? 답변: 이는 일반적으로 잘못된 경로 구성 때문입니다. 다음을 확인하세요.

1. .env 파일의 OMCP_VAULT_PATH 는 Windows에서도 슬래시( / )를 사용합니다.
2. 경로는 절대 경로입니다(루트에서 시작)
3. 경로는 끝에 슬래시로 끝나지 않습니다.
4. 볼트 디렉토리가 존재하며 접근 가능합니다.

질문: 권한 오류가 발생하는 이유는 무엇인가요? 답변: 일반적으로 다음과 같은 경우에 발생합니다.

1. 볼트 경로는 제한된 디렉토리를 가리킵니다.
2. Python 프로세스에는 읽기/쓰기 권한이 없습니다.
3. 보관소는 현재 동기화 중인 클라우드 동기화 폴더(예: OneDrive)에 있습니다.

노력하다:

1. 로컬 디렉토리로 볼트 이동
2. 상승된 권한으로 서버 실행
3. 바이러스 백신 검사가 액세스를 차단하지 않는지 확인하세요.

클라이언트 연결 문제

질문: AI 클라이언트가 서버에 연결할 수 없습니다. 무엇을 확인해야 하나요? 답변: 다음과 같은 일반적인 문제를 확인하세요.

1. 서버가 실제로 실행 중입니다(터미널 출력 확인)
2. 클라이언트 구성의 포트가 서버의 포트와 일치합니다.
3. 클라이언트 구성의 Python 경로는 올바른 가상 환경을 가리킵니다.
4. 모든 환경 변수는 클라이언트 구성에 올바르게 설정되어 있습니다.

질문: "연결이 거부되었습니다" 오류가 발생하는 이유는 무엇인가요? 답변: 이는 일반적으로 다음과 같은 의미입니다.

1. 서버가 실행되지 않습니다
2. 포트가 이미 사용 중입니다
3. 방화벽이 연결을 차단하고 있습니다

노력하다:

1. 서버가 실행 중인지 확인하세요: netstat -ano | findstr :8001 (Windows)
2. .env 에서 OMCP_SERVER_PORT 설정하여 다른 포트를 시도해 보세요.
3. 테스트를 위해 방화벽을 일시적으로 비활성화합니다.

질문: "[오류] [obsidian_vault] 예기치 않은 토큰 'S', "시작 O"... 유효한 JSON이 아닙니다"라는 메시지가 표시됩니다. 무엇이 문제인가요? 답변: 이 오류는 클라이언트의 JSON 구성 파일 형식이 잘못되었을 때 발생합니다. 일반적인 원인은 다음과 같습니다.

1. JSON에 쉼표가 없거나 추가됨
2. Windows 경로의 이스케이프되지 않은 백슬래시
3. JSON의 주석(JSON은 주석을 지원하지 않습니다)

클라이언트 구성 파일을 확인하세요(예: claude_desktop_config.json ):

1. JSON 검증기(예: jsonlint.com )를 사용하여 구문을 검사합니다.
2. Windows 경로의 경우 백슬래시를 이스케이프합니다: "C:\\path\\to\\file"
3. 모든 주석(// 또는 /* */)을 제거하세요.
4. 모든 문자열이 올바르게 인용되었는지 확인하세요.
5. 모든 브래킷과 브레이스가 제대로 닫혔는지 확인하세요

올바른 Windows 경로 형식의 예:

질문: 시간 초과 오류와 "서버 연결 끊김" 메시지가 나타납니다. 무슨 일인가요? 답변: 이 오류 패턴(초기화 성공 후 60초 후 시간 초과)은 일반적으로 다음과 같은 경우를 의미합니다.

1. 서버가 이미 다른 프로세스에서 실행 중입니다.
2. 해당 포트는 이미 다른 애플리케이션에서 사용 중입니다.
3. 서버 프로세스가 예기치 않게 종료됩니다.

다음 단계를 순서대로 시도해 보세요.

1. 실행 중인 서버 프로세스를 확인하세요.
   # On Windows netstat -ano | findstr :8001 # Look for the PID and then: taskkill /F /PID <PID>
   # On Linux/macOS lsof -i :8001 # Look for the PID and then: kill -9 <PID>
2. 해당 포트를 사용하는 다른 애플리케이션을 확인하세요.
   • 포트 8001을 사용할 수 있는 다른 모든 애플리케이션을 닫으세요.
   • 여기에는 다른 MCP 서버, 개발 서버 또는 모든 웹 애플리케이션이 포함됩니다.
   • 확실하지 않다면 .env 에서 포트를 변경해보세요.
     OMCP_SERVER_PORT=8002
3. 서버 프로세스 확인:
   • 작업 관리자(Windows) 또는 활동 모니터(macOS)를 엽니다.
   • MCP 서버와 관련된 Python 프로세스를 찾으세요.
   • 의심스러운 프로세스를 종료하세요
4. 시스템 리소스를 확인하세요:
   • 충분한 메모리와 CPU를 사용할 수 있는지 확인하세요.
   • 바이러스 백신이나 보안 소프트웨어가 프로세스를 차단하고 있는지 확인하세요.
   • Python 환경에 적절한 권한이 있는지 확인하세요.
5. 모든 것을 재설정합니다:
   • 클라이언트 애플리케이션을 중지합니다
   • 남아 있는 모든 서버 프로세스를 종료합니다.
   • .env 파일을 삭제하고 .env.example 에서 새 파일을 만듭니다.
   • 컴퓨터를 다시 시작하세요(다른 단계가 효과가 없는 경우)
   • 클라이언트 애플리케이션으로 새롭게 시작하세요

위의 모든 단계를 시도한 후에도 문제가 지속되면 공유해 주세요.

1. 전체 오류 로그
2. netstat -ano | findstr :8001 (Windows) 또는 lsof -i :8001 (Linux/macOS)의 출력
3. 시스템 이벤트 로그의 오류 메시지

질문: "서버 전송이 예기치 않게 종료되었습니다... 프로세스가 일찍 종료됩니다"라는 메시지와 함께 서버 연결이 즉시 끊어집니다. 무엇이 문제인가요? 답변: 이 오류는 Python 서버 프로세스가 클라이언트에서 실행된 직후에 작동이 중단되었음을 의미합니다. 시간 초과가 아니라 서버 스크립트 자체가 실행되지 않았거나 계속 실행 중이 아니었습니다.

일반적인 원인:

1. 클라이언트 JSON의 잘못된 경로:
   • command``.venv내부의 올바른 python.exe 가리키지 않습니다.
   • args 올바른 obsidian_mcp_server/main.py 스크립트를 가리키지 않습니다.
   • Windows에서 경로 구분 기호가 잘못되었거나 백슬래시 이스케이프( \\ )가 누락되었습니다.
2. 종속성 누락:
   • requirements.txt 에 필요한 패키지가 .venv 에 설치되지 않았습니다.
   • 클라이언트가 가상 환경을 제대로 활성화하지 않고 Python을 시작합니다.
3. 구문 오류: 최근 코드 변경으로 인해 Python 구문 오류가 발생했습니다.
4. 중요 구성/권한 오류:
   • 시작 시 .env 파일을 읽는 중 오류가 발생했습니다.
   • OMCP_VAULT_PATH 잘못되었거나 액세스할 수 없습니다.
   • Python 프로세스에 파일을 실행하거나 액세스할 수 있는 권한이 없습니다.
5. 조기 처리되지 않은 예외: 서버가 수신을 시작하기 전에 초기 설정 중에 오류가 발생합니다.

문제 해결 단계:

1. 클라이언트 JSON 경로 확인: 클라이언트 JSON 구성에서 command 및 args 의 절대 경로를 다시 확인하세요. Windows 경로에는 이스케이프된 백슬래시( \\ )를 사용하세요.
2. 수동으로 테스트하기(중요 단계):
   • 터미널에서 가상 환경을 활성화하세요:
     # On Windows .\.venv\Scripts\activate
     # On Linux/macOS source .venv/bin/activate
   • 서버를 직접 실행합니다.
     python obsidian_mcp_server/main.py
   • 터미널에 직접 출력된 오류 메시지를 자세히 살펴보세요. 이렇게 하면 클라이언트를 우회하여 근본 원인(예: ImportError , SyntaxError , FileNotFoundError )을 파악할 수 있습니다.
3. 종속성 확인: venv가 활성화된 상태에서 pip check 및 pip install -r requirements.txt 실행합니다.
4. .env 및 Vault 경로 검증: .env 존재하고 읽을 수 있으며 OMCP_VAULT_PATH 가 올바른지 확인합니다(슬래시 / ) 사용).
5. 최근 코드 변경 사항 검토: 최근 편집된 Python 파일에 구문 오류나 문제가 있는지 확인합니다.

참고 작업

질문: 특정 폴더에서 노트를 만들거나 편집할 수 없는 이유는 무엇인가요? 답변: 다음과 같은 이유 때문일 수 있습니다.

1. 경로 보안 제한(볼트 외부에서 쓰기 시도)
2. 폴더 권한
3. 다른 프로세스의 파일 잠금

노력하다:

1. 볼트 내에서 상대 경로 사용
2. 폴더 권한 확인
3. 파일이 열려 있을 수 있는 다른 프로그램을 닫습니다.

질문: 메모 업데이트가 저장되지 않는 이유는 무엇인가요? 답변: 일반적인 원인:

1. 노트 경로가 올바르지 않습니다
2. 콘텐츠 형식이 잘못되었습니다
3. 백업 생성에 실패했습니다

확인하다:

1. 노트 경로가 존재하며 접근 가능합니다.
2. 내용은 유효한 마크다운입니다
3. 백업 디렉토리에는 쓰기 권한이 있습니다.

일일 노트

질문: 내 일일 노트가 올바른 위치에 생성되지 않는 이유는 무엇인가요? 답변: 확인해 보세요.

1. .env 에 OMCP_DAILY_NOTE_LOCATION 이 올바르게 설정되었습니다.
2. 경로는 슬래시를 사용합니다.
3. 대상 폴더가 존재합니다
4. 날짜 형식은 보관소 설정과 일치합니다.

일반적인 문제 해결

질문: 서버가 제대로 작동하는지 어떻게 확인하나요? 답변: 테스트 클라이언트를 실행하세요.

이렇게 하면 일련의 작업이 수행되고 문제가 보고됩니다.

질문: 오류 로그는 어디에서 찾을 수 있나요? 답변: 다음을 확인하세요.

1. 서버가 실행 중인 터미널
2. 실패한 작업에 대한 백업 디렉토리
3. 권한 문제에 대한 시스템 이벤트 로그

질문: 모든 것을 재설정하여 새롭게 시작하려면 어떻게 해야 하나요? 답변: 다음 단계를 시도해 보세요.

1. 서버를 중지합니다
2. .env 파일을 삭제하세요
3. .env.example 에서 새 .env 만듭니다.
4. 서버를 다시 시작하세요

기여를 환영합니다!