Obsidian Knowledge MCP

읽기 전용 Obsidian-to-PostgreSQL 임포터이자 MCP 서버입니다. 볼트가 진실의 원천입니다. 수집은 Markdown 파일을 읽기만 하며 파일을 절대 편집하거나 삭제하지 않습니다.

아키텍처

Obsidian vault -> Python parser/upsert importer -> PostgreSQL -> FastMCP tools/resources -> Claude Connector

문서는 상대 경로와 원본 Markdown 본문을 유지합니다. 각 노트는 document 노드가 되고, [[links]]는 방향성 있는 related_to 엣지와 document_links가 됩니다. 태그, 별칭, 제목, 인식되지 않은 frontmatter는 JSONB에 보존됩니다. 존재하지 않는 링크 대상은 로그에 기록되고 건너뜁니다. 수집을 다시 실행하면 파일 경로를 기준으로 레코드를 업데이트하고 중복 엣지/태그를 방지합니다.

Related MCP server: Semantic Notes Vault MCP

설정

요구 사항: Python 3.11+, Docker Desktop, 그리고 수동 SQL 검사를 원하는 경우에만 PostgreSQL 클라이언트.

1. .env.example을 .env로 복사하고 POSTGRES_PASSWORD를 설정한 다음, OBSIDIAN_VAULT_PATH를 기존 볼트로 설정하세요. 원치 않는다면 볼트를 이 프로젝트 안에 두지 마세요.

2. 환경을 만들고 의존성을 설치하세요:

   py -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -e ".[test]"

3. PostgreSQL을 시작하세요. 포트는 localhost에만 바인딩됩니다:

   docker compose up -d postgres

4. 볼트를 임포트하세요:

   python -m ingestion.importer
   # or: obsidian-ingest "C:\path\to\vault"

5. 확인하세요:

   docker compose exec postgres psql -U knowledge_app -d knowledge -c "select count(*) from documents; select count(*) from edges;"
   pytest

스키마는 초기화 스크립트로 마운트됩니다. 기존 볼륨의 경우 psql -f database/schema.sql을 사용해 변경 사항을 명시적으로 적용하세요.

Render에 배포

이 저장소에는 Render 무료 Web Service용 render.yaml이 포함되어 있습니다. Render에서 이 저장소로 새 Blueprint를 만들고 배포하세요. Render가 MCP_AUTH_TOKEN을 생성하고 자체 PORT를 사용합니다. Render는 관리형 PostgreSQL 서비스에 결제 정보를 요구하므로, Neon이나 Supabase 같은 무료 외부 PostgreSQL 제공업체의 DATABASE_URL을 제공하세요. 쿼리하기 전에 해당 데이터베이스에 database/schema.sql을 적용하세요. 기본 공개 엔드포인트는 다음과 같습니다:

https://obsidian-knowledge-mcp.onrender.com/mcp

서비스 이름을 변경하면 Render 환경의 MCP_PUBLIC_URL을 결과로 나오는 https://<service-name>.onrender.com URL로 업데이트하세요. MCP_PUBLIC_URL에 /mcp를 추가하지 마세요. /mcp는 Claude Connector URL에만 속합니다.

Render 서비스는 Windows 또는 OneDrive 볼트를 읽을 수 없습니다. 볼트와 데이터베이스에 모두 접근할 수 있는 머신에서 외부 PostgreSQL 데이터베이스로 볼트를 임포트하거나, 쿼리하기 전에 Render에서 접근 가능한 별도의 스토리지/임포트 작업을 추가하세요.

MCP 서버

로컬에서 다음과 같이 실행하세요:

python -m mcp_server.server

기본 엔드포인트는 Streamable HTTP를 사용하는 http://127.0.0.1:8000/mcp입니다. 로컬 클라이언트의 경우 MCP_TRANSPORT=stdio로 설정하고 obsidian-mcp를 명령어로 사용하세요. 서버는 search_knowledge, get_node, get_document, get_related_nodes, find_path, list_nodes, search_documents와 knowledge://node/{node_name} 리소스를 제공합니다. 제한은 최대 100이며 SQL은 매개변수화됩니다.

Claude Connector

Claude Connector는 PostgreSQL 엔드포인트가 아닌 원격에서 도달 가능한 MCP 엔드포인트가 필요합니다. Claude 설정 -> 커넥터에서 /mcp로 끝나는 Render URL을 추가하세요(예: https://obsidian-knowledge-mcp.onrender.com/mcp). 프롬프트가 표시되면 생성된 MCP_AUTH_TOKEN을 bearer 토큰으로 사용하고, Claude 작업 공간에서 요구하는 인증 흐름을 완료한 다음, What do I have in my knowledge base about Python?로 테스트하세요.

프로덕션에서는 정적 토큰 대신 ID 인식 프록시(OAuth/OIDC) 또는 mTLS를 사용하세요. 포트 5432를 노출하지 마세요. Claude가 연결 오류를 보고하면 docker compose ps, docker compose logs postgres, MCP 프로세스 로그, HTTPS 인증서/DNS, /mcp의 프록시 전달, 엔드포인트가 네트워크 외부에서 도달 가능한지 확인하세요. 인증된 헬스 체크를 데이터베이스 오류와 분리하고 스택 트레이스를 노출하지 마세요.

예시 쿼리

• Machine Learning에 연결된 개념은 무엇인가요?

• Python과 Artificial Intelligence 사이의 관계 경로를 찾아주세요.

• RAG에서 두 홉 이내에 있는 개념은 무엇인가요?

• Python과 Machine Learning을 모두 언급하는 문서는 무엇인가요?

가정 및 확장 지점

이 작업 공간에는 검사할 볼트가 없었으므로 파싱은 표준 Obsidian 규칙을 따르며 tests/test_parser.py의 픽스처로 검증됩니다. Dataview 관련 구문은 콘텐츠로 보존됩니다. 저장소 계층이 SQL을 MCP에서 분리하므로, MCP 계약을 변경하지 않고도 향후 양방향 동기화가 가능합니다. MCP_AUTH_TOKEN은 Streamable HTTP 서버에서 적용됩니다. 더 강력한 프로덕션 접근 제어를 위해 ID 인식 프록시(OAuth/OIDC)를 사용하세요.