흑요석 MCP 서버

로컬 REST API 플러그인을 통해 AI 에이전트가 Obsidian 볼트에서 정교한 지식 검색 및 분석을 수행할 수 있도록 하는 MCP(모델 컨텍스트 프로토콜) 서버입니다.

이것이 중요한 이유

이 서버는 Obsidian 볼트를 AI 에이전트를 위한 강력한 지식 기반으로 변환하여 다음과 같은 복잡한 다단계 워크플로를 지원합니다.

4월 1일 이후에 작성된 '프로젝트/계획' 폴더에서 '로드맵' 또는 '타임라인'이라는 제목의 메모를 검색하여 방해 요소나 종속성이 있는지 분석하고, 출처 메모를 참조하여 통합 위험 평가를 제시합니다.
"지난 달에 '연구' 또는 '분석' 태그가 달린 모든 노트를 찾아 내용을 검토하여 불완전한 섹션이나 미해결 질문을 찾은 다음, '팀/전문성' 노트와 교차 참조하여 각 격차를 해소하는 데 도움이 될 수 있는 동료를 제안합니다."
"예산이나 인원 수를 포함한 '리더십/분기별' 회의록의 전체 내용을 가져와서 부서에 할당된 작업 항목을 분석하고 출처 메모 참조를 사용하여 연대순 타임라인을 만듭니다."

서버의 고급 필터링, 정규 표현식 지원, 그리고 전체 콘텐츠 검색 기능을 통해 에이전트는 수동으로 몇 시간이 걸리는 섬세한 지식 작업을 수행할 수 있습니다.

Related MCP server: Obsidian MCP Server

필수 조건

Obsidian 볼트에 Obsidian Local REST API 플러그인을 설치하세요
Obsidian 설정에서 플러그인을 구성하고 활성화하세요
API URL(기본값: https://localhost:27124 )과 API 키를 설정한 경우 이를 기록해 두십시오.

설치

PyPI에서 (권장)

지엑스피1

MCP 구성에 추가

MCP 클라이언트 구성(예: Claude Desktop)에 다음을 추가합니다.

{
  "mcpServers": {
    "obsidian-api-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "obsidian-api-mcp-server>=1.0.1",
        "obsidian-api-mcp"
      ],
      "env": {
        "OBSIDIAN_API_URL": "https://localhost:27124",
        "OBSIDIAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

소스(개발)에서

# Clone the repository
git clone https://github.com/pmmvr/obsidian-api-mcp-server
cd obsidian-api-mcp-server

# Install with uv
uv pip install -e .

# Or with pip
pip install -e .

구성

Obsidian API에 대한 환경 변수를 설정합니다.

# Required: Obsidian API URL (HTTPS by default)
export OBSIDIAN_API_URL="https://localhost:27124"  # Default

# Optional: API key if you've configured authentication
export OBSIDIAN_API_KEY="your-api-key-here"

중요 보안 참고 : OBSIDIAN_API_KEY 를 스크립트에 직접 하드코딩하거나 버전 관리 시스템에 커밋하지 마세요. .env 파일(이 프로젝트의 .gitignore 파일에 포함되어 있음)과 python-dotenv 와 같은 라이브러리를 사용하여 API 키를 관리하거나, 운영 체제 또는 셸에서 관리하는 환경 변수를 사용하는 것이 좋습니다.

참고 : 서버는 기본적으로 HTTPS를 사용하며, 로컬 Obsidian 인스턴스에서 일반적으로 사용되는 자체 서명 인증서에 대한 SSL 인증서 검증을 비활성화합니다. HTTP 연결의 경우 OBSIDIAN_API_URL="http://localhost:27123" 설정하세요.

용법

MCP 서버를 실행합니다.

obsidian-mcp

사용 가능한 도구

서버는 세 가지 강력한 도구를 제공합니다.

search_vault - 유연한 필터와 전체 콘텐츠 검색 기능을 갖춘 고급 검색:
- query - 노트 콘텐츠 전체에서 텍스트 또는 정규식 검색(선택 사항)
- query_type - 검색 유형: "text"(기본값) 또는 "regex"
- search_in_path - 특정 폴더 경로로 검색 제한
- title_contains - 노트 제목의 텍스트로 필터링(문자열, 배열 또는 JSON 문자열)
- title_match_mode - 여러 용어를 일치시키는 방법: "any"(OR) 또는 "all"(AND)
- tag - 태그로 필터링(문자열, 배열 또는 JSON 문자열 - 프론트매터 및 인라인 #태그 검색)
- tag_match_mode - 여러 태그를 일치시키는 방법: "any"(OR) 또는 "all"(AND)
- context_length - 반환할 콘텐츠의 양(전체 콘텐츠의 경우 높게 설정)
- include_content - 일치하는 모든 노트의 전체 내용을 검색하는 부울 값입니다.
- created_since/until - 생성 날짜로 필터링
- modified_since/until - 수정 날짜로 필터링
- page_size - 페이지당 결과
- max_matches_per_file - 노트당 일치 항목 제한
주요 특징 :
- query 제공되지 않으면 필터 전용 검색에 대해 전체 콘텐츠가 자동으로 반환됩니다.
- include_content=True 는 모든 검색에 대해 전체 콘텐츠를 검색하도록 강제합니다.
- 복잡한 텍스트 일치(OR 조건, 대소문자 구분 없이 검색 등)를 위한 정규식 패턴을 지원합니다.
get_note_content - 경로별로 특정 노트의 전체 콘텐츠 및 메타데이터를 검색합니다.
browse_vault_structure - 볼트 디렉토리 구조를 효율적으로 탐색합니다.
- path - 찾아볼 디렉토리(기본값은 볼트 루트)
- include_files - 파일을 포함할지 여부에 대한 부울 값(기본값: False, 속도를 위해 폴더만 포함)
- recursive - 모든 중첩 디렉토리를 탐색하기 위한 부울 값

예시 사용 사례

기본 검색

특정 폴더에서 제목으로 노트 찾기:

search_vault(
  search_in_path="Work/Projects/",
  title_contains="meeting"
)

여러 개의 제목 용어가 포함된 노트 찾기(OR 논리):

search_vault(
  title_contains=["foo", "bar", "fizz", "buzz"],
  title_match_mode="any"  # Default
)

모든 제목 용어(및 논리)가 포함된 노트 찾기:

search_vault(
  title_contains=["project", "2024"],
  title_match_mode="all"
)

전체 내용이 포함된 최근 노트를 모두 받으세요:

search_vault(
  modified_since="2025-05-20",
  include_content=True
)

컨텍스트를 활용한 텍스트 검색:

search_vault(
  query="API documentation",
  search_in_path="Engineering/",
  context_length=500
)

태그로 검색:
```
search_vault(
  tag="project"
)
```

OR 조건에 대한 정규식 검색:

search_vault(
  query="foo|bar",
  query_type="regex",
  search_in_path="Projects/"
)

특정 사람에게 할당된 작업에 대한 정규식 검색:

search_vault(
  query="(TODO|FIXME|ACTION).*@(alice|bob)",
  query_type="regex",
  search_in_path="Work/Meetings/"
)

고급 다단계 워크플로

다음 예는 에이전트가 정교한 지식 발견 작업을 어떻게 연결할 수 있는지 보여줍니다.

전략적 프로젝트 분석:

# Step 1: Get all project documentation
search_vault(
  search_in_path="Projects/Infrastructure/",
  title_contains=["planning", "requirements", "architecture"],
  title_match_mode="any",
  include_content=True
)

# Step 2: Find related technical discussions
search_vault(
  tag=["infrastructure", "technical-debt"],
  tag_match_mode="any",
  modified_since="2025-04-01",
  include_content=True
)

그런 다음 에이전트는 종속성을 분석하고 위험을 식별하며 리소스 할당을 권장할 수 있습니다.

회의 작업 항목 마이닝:

# Get all recent meeting notes with full content
search_vault(
  search_in_path="Meetings/",
  title_contains=["standup", "planning", "retrospective"],
  title_match_mode="any",
  created_since="2025-05-01",
  include_content=True
)

에이전트는 작업 항목에 대한 콘텐츠를 스캔하고, 할당을 추출하고, 연대순 추적을 생성합니다.

연구 갭 분석:

# Find research notes with questions or gaps
search_vault(
  query="(TODO|QUESTION|INVESTIGATE|UNCLEAR)",
  query_type="regex",
  tag=["research", "analysis"],
  tag_match_mode="any",
  include_content=True
)

# Cross-reference with team expertise
search_vault(
  search_in_path="Team/",
  tag=["expertise", "skills"],
  tag_match_mode="any",
  include_content=True
)

에이전트는 지식 격차를 파악하고 도움을 줄 수 있는 팀원을 제안합니다.

금고 구조 탐험:

# Quick organizational overview
browse_vault_structure(recursive=True)

# Deep dive into specific areas
browse_vault_structure(
  path="Projects/CurrentSprint/",
  include_files=True,
  recursive=True
)

태그 기반 지식 매핑:

# Find notes with multiple tags (AND logic)
search_vault(
  tag=["project", "urgent"],
  tag_match_mode="all",
  include_content=True
)

# Find notes with any relevant tags (OR logic)
search_vault(
  tag=["architecture", "design", "implementation"],
  tag_match_mode="any",
  modified_since="2025-04-15"
)

개발

# Install with test dependencies
uv pip install -e ".[test]"

# Run the server
python -m obsidian_mcp.server

# Run tests
uv run behave features/blackbox_tests.feature
# Or use the test runner
python run_tests.py

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

Obsidian MCP Server