흑요석 MCP 서버

LLM이 Obsidian 볼트와 상호 작용하도록 설계된 모델 컨텍스트 프로토콜 서버입니다. TypeScript로 구축되었으며 안전한 API 통신, 효율적인 파일 작업, 포괄적인 검색 기능을 갖추고 있어 AI 어시스턴트가 깔끔하고 유연한 도구 인터페이스를 통해 지식 베이스를 원활하게 관리할 수 있도록 지원합니다.

모델 컨텍스트 프로토콜(MCP)을 사용하면 AI 모델이 표준화된 인터페이스를 통해 외부 도구 및 리소스와 상호 작용할 수 있습니다.

Obsidian의 로컬 REST API 플러그인이 필요합니다.

특징

파일 작업

검증을 통한 원자적 파일/디렉토리 작업
자원 모니터링 및 정리
오류 처리 및 우아한 실패

검색 시스템

구성 가능한 컨텍스트를 사용한 전체 텍스트 검색
파일, 태그 및 메타데이터에 대한 고급 JsonLogic 쿼리
글로브 패턴 및 프런트매터 필드 지원

부동산 관리

YAML 프론트매터 파싱 및 지능형 병합
자동 타임스탬프(Obsidian에서 생성, 서버에서 수정)
사용자 정의 필드 지원

보안 및 성능

속도 제한 및 SSL 옵션이 있는 API 키 인증
리소스 모니터링 및 상태 점검
우아한 종료 처리

설치

참고: Node.js가 필요합니다.

Obsidian에서 로컬 REST API 플러그인 활성화
복제 및 빌드:

지엑스피1

또는 npm에서 설치하세요:

npm install obsidian-mcp-server

구성

MCP 클라이언트 설정에 다음을 추가합니다(예: claude_desktop_config.json 또는 cline_mcp_settings.json ):

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/build/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "your_api_key_here",
        "VERIFY_SSL": "false",
        "OBSIDIAN_PROTOCOL": "https",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124",
        "REQUEST_TIMEOUT": "5000",
        "MAX_CONTENT_LENGTH": "52428800",
        "MAX_BODY_LENGTH": "52428800",
        "RATE_LIMIT_WINDOW_MS": "900000",
        "RATE_LIMIT_MAX_REQUESTS": "200",
        "TOOL_TIMEOUT_MS": "60000"
      }
    }
  }
}

환경 변수:

필수의:

OBSIDIAN_API_KEY : Obsidian의 로컬 REST API 플러그인 설정의 API 키

연결 설정:

VERIFY_SSL : SSL 인증서 검증을 활성화합니다(기본값: false). # 자체 서명 인증서의 경우 false로 설정해야 합니다. 로컬에서 실행 중이거나 무슨 뜻인지 잘 모르겠다면 false로 설정하세요.
OBSIDIAN_PROTOCOL : 사용할 프로토콜(기본값: "https")
OBSIDIAN_HOST : 호스트 주소(기본값: "127.0.0.1")
OBSIDIAN_PORT : 포트 번호(기본값: 27124)

요청 제한:

REQUEST_TIMEOUT : 요청 시간 초과(밀리초) (기본값: 5000)
MAX_CONTENT_LENGTH : 최대 응답 콘텐츠 길이(바이트)(기본값: 52428800[50MB])
MAX_BODY_LENGTH : 최대 요청 본문 길이(바이트)(기본값: 52428800[50MB])

속도 제한:

RATE_LIMIT_WINDOW_MS : 밀리초 단위의 속도 제한 창(기본값: 900000[15분])
RATE_LIMIT_MAX_REQUESTS : 윈도우당 최대 요청 수(기본값: 200)

도구 실행:

TOOL_TIMEOUT_MS : 도구 실행 시간 초과(밀리초) (기본값: 60000[1분])

프로젝트 구조

이 프로젝트는 관심사를 명확하게 분리한 모듈형 아키텍처를 따릅니다.

src/
  ├── index.ts          # Main entry point
  ├── mcp/              # MCP server implementation
  ├── obsidian/         # Obsidian API client and types
  ├── resources/        # MCP resource implementations
  ├── tools/            # MCP tool implementations
  │   ├── files/        # File operations tools
  │   ├── search/       # Search tools
  │   └── properties/   # Property management tools
  └── utils/            # Shared utilities

도구

파일 관리

// List vault contents
obsidian_list_files_in_vault: {
}

// List directory contents
obsidian_list_files_in_dir: {
  dirpath: string; // Path relative to vault root
}

// Get file contents
obsidian_get_file_contents: {
  filepath: string; // Path relative to vault root
}

검색 작업

// Text search with context
obsidian_find_in_file: {
  query: string,
  contextLength?: number  // Default: 10
}

// Advanced search with JsonLogic
obsidian_complex_search: {
  query: JsonLogicQuery
  // Examples:
  // Find by tag:
  // {"in": ["#mytag", {"var": "frontmatter.tags"}]}
  //
  // Find markdown files in a directory:
  // {"glob": ["docs/*.md", {"var": "path"}]}
  //
  // Combine conditions:
  // {"and": [
  //   {"glob": ["*.md", {"var": "path"}]},
  //   {"in": ["#mytag", {"var": "frontmatter.tags"}]}
  // ]}
}

// Get all tags in vault or directory
obsidian_get_tags: {
  path?: string  // Optional: limit to specific directory
}

콘텐츠 수정

// Append to file
obsidian_append_content: {
  filepath: string,  // Path relative to vault root
  content: string    // Content to append
}

// Update file content
obsidian_patch_content: {
  filepath: string,  // Path relative to vault root
  content: string    // New content (replaces existing)
}

부동산 관리

// Get note properties
obsidian_get_properties: {
  filepath: string  // Path relative to vault root
}

// Update note properties
obsidian_update_properties: {
  filepath: string,  // Path relative to vault root
  properties: {
    title?: string,
    author?: string,
    // Note: created/modified timestamps are managed automatically
    type?: Array<"concept" | "architecture" | "specification" |
      "protocol" | "api" | "research" | "implementation" |
      "guide" | "reference">,
    tags?: string[],  // Must start with #
    status?: Array<"draft" | "in-progress" | "review" | "complete">,
    version?: string,
    platform?: string,
    repository?: string,  // URL
    dependencies?: string[],
    sources?: string[],
    urls?: string[],      // URLs
    papers?: string[],
    custom?: Record<string, unknown>
  }
}

모범 사례

파일 작업

검증과 함께 원자 연산을 사용하세요
오류 처리 및 성능 모니터링

검색 구현

해당 작업에 적합한 검색 도구를 사용하세요.
- 텍스트 검색을 위한 obsidian_find_in_file
- 메타데이터/태그 필터링을 위한 obsidian_complex_search
컨텍스트 크기를 적절하게 유지하세요(기본값: 10자)

부동산 관리

적절한 유형을 사용하고 업데이트를 검증하세요
배열과 사용자 정의 필드를 적절하게 처리하세요
타임스탬프를 설정하지 마세요(자동으로 관리됨)

오류 방지

입력을 검증하고 오류를 우아하게 처리합니다.
패턴을 모니터링하고 요금 한도를 존중하세요

자원

MCP 서버는 다음과 같은 리소스를 제공합니다.

obsidian://tags  # List of all tags used across the vault

기여하다

저장소를 포크하세요
기능 브랜치 생성
풀 리퀘스트 제출

버그와 기능에 대한 문의는 https://github.com/cyanheads/obsidian-mcp-server/issues 에서 해주세요.

출판

버전 태그가 푸시되면 패키지는 자동으로 npm에 게시됩니다.

# Update version in package.json
npm version patch  # or minor, or major
git push --follow-tags

이렇게 하면 GitHub Action이 트리거되어 패키지를 빌드하고 게시합니다.

특허

아파치 라이선스 2.0

Obsidian MCP Server

Integrations

흑요석 MCP 서버

특징

파일 작업

검색 시스템

부동산 관리

보안 및 성능

설치

구성

프로젝트 구조

도구

파일 관리

검색 작업

콘텐츠 수정

부동산 관리

모범 사례

파일 작업

검색 구현

부동산 관리

오류 방지

자원

기여하다

출판

특허

Tools

Related Resources

Appeared in Searches