MCP를 지원하는 로컬 REST API

보안 인증 REST API를 통해 스크립트, 브라우저 확장 프로그램, AI 에이전트가 Obsidian 볼트에 직접 연결할 수 있게 해주세요.

• 대화형 API 문서: https://coddingtonbear.github.io/obsidian-local-rest-api/

• Obsidian 커뮤니티 페이지: https://community.obsidian.md/plugins/obsidian-local-rest-api/

• 할 수 있는 작업

• 빠른 시작

  • REST API

  • MCP 클라이언트

    • Claude Code

    • Claude Desktop

    • Cursor

    • 기타 클라이언트

• API 개요

• 노트 패치

  • 원시 콘텐츠 모드

• 특정 섹션 지정

• 검색

• MCP (Model Context Protocol)

  • 프로토콜 개정

  • 클라이언트 연결

  • 사용 가능한 도구

  • 사용 가능한 리소스

• API 확장

  • 타입 기반 확장 API

  • 알려진 확장

• 기여

• 크레딧

할 수 있는 작업

REST API 또는 **내장 MCP 서버**를 통해 볼트에 접근하세요. 두 인터페이스 모두 동일한 핵심 기능을 제공하므로 스크립트, 브라우저 확장 프로그램, AI 에이전트가 모두 같은 방식으로 통신할 수 있습니다.

• 노트 읽기, 생성, 업데이트, 삭제 — 바이너리 파일을 포함한 볼트의 모든 파일에 대한 전체 CRUD

• 특정 섹션 정밀 패치 — 헤딩, 블록 참조 또는 frontmatter 키를 대상으로 해당 섹션만 추가, 앞에 삽입, 교체, 삭제 또는 이동하고 파일의 나머지 부분은 건드리지 않습니다

• 볼트 검색 — 간단한 전체 텍스트 검색 또는 노트 메타데이터(frontmatter, 태그, 경로, 콘텐츠)에 대한 구조화된 JsonLogic 쿼리

• 활성 파일 접근 — Obsidian에서 현재 열려 있는 노트 읽기 또는 쓰기

• 명령 나열 및 실행 — 명령 팔레트를 사용한 것처럼 모든 Obsidian 명령 실행

• 태그 쿼리 — 볼트 전체의 모든 태그와 사용 횟수 나열

• Obsidian에서 파일 열기 — Obsidian UI에서 특정 노트를 열도록 지시

• API 확장 — 다른 플러그인이 API 확장 인터페이스를 통해 자체 라우트를 등록할 수 있습니다

모든 요청은 자체 서명 인증서로 HTTPS를 통해 제공되며 API 키 인증으로 보호됩니다.

Related MCP server: Connect MCP

빠른 시작

플러그인을 설치하고 활성화한 후 설정 → Local REST API를 열어 API 키와 인증서를 확인하세요.

REST API

# Check the server is running (no auth required)
curl -k https://127.0.0.1:27124/

# List files at the root of your vault
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/

# Read a note
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md

# Read a specific heading (URL-embedded target)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append a line to a specific heading (PATCH with a JSON instruction)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["My Section"],"operation":"append","content":"New line of content"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

인증서 경고를 피하려면 https://127.0.0.1:27124/obsidian-local-rest-api.crt에서 인증서를 다운로드하여 신뢰하거나 HTTP 클라이언트가 이를 직접 가리키도록 설정할 수 있습니다.

MCP 클라이언트

MCP 서버는 https://127.0.0.1:27124/mcp/에서 실행되며 Authorization 헤더(예: Authorization: Bearer <your-api-key>)를 통해 베어러 토큰을 제공하여 인증해야 합니다. 플러그인은 자체 서명 인증서를 사용하므로 OS/클라이언트에서 인증서를 신뢰하거나 http://127.0.0.1:27123/mcp/의 일반 HTTP 엔드포인트를 사용해야 할 수 있습니다(설정 → Local REST API → Enable HTTP server에서 활성화).

Claude Code

Claude Code는 네이티브 HTTP MCP를 지원합니다. 서버를 추가하는 가장 빠른 방법은 CLI를 사용하는 것입니다:

claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \
  --header "Authorization: Bearer <your-api-key>"

또는 프로젝트 루트의 .mcp.json에 수동으로 추가하거나(프로젝트 범위) claude mcp add --scope user를 통해 사용자 전체에 구성할 수 있습니다:

{
  "mcpServers": {
    "obsidian": {
      "type": "http",
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Claude Desktop

Claude Desktop은 원격 HTTP MCP 서버를 기본적으로 지원하지 않지만, mcp-remote로 브리지할 수 있습니다(Node.js 필요). claude_desktop_config.json에 다음을 추가하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://127.0.0.1:27124/mcp/",
        "--header",
        "Authorization: Bearer <your-api-key>"
      ]
    }
  }
}

파일을 저장한 후 Claude Desktop을 다시 시작하세요.

Cursor

Cursor는 Streamable HTTP MCP 전송을 지원합니다. ~/.cursor/mcp.json(전역) 또는 .cursor/mcp.json(프로젝트별)에 다음을 추가하세요:

{
  "mcpServers": {
    "obsidian": {
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

기타 클라이언트

Streamable HTTP 전송을 지원하는 모든 MCP 클라이언트는 Authorization: Bearer <your-api-key> 헤더와 함께 https://127.0.0.1:27124/mcp/에 연결할 수 있습니다. 정확한 구성 형식은 클라이언트의 문서를 참조하세요.

API 개요

전체 요청/응답 세부 정보는 대화형 문서를 참조하세요.

노트 패치

PATCH 메서드는 이 API의 가장 유용한 기능 중 하나입니다. 전체 파일을 다시 쓰지 않고도 대상이 지정된 편집을 할 수 있습니다.

JSON 명령을 보내세요: 대상의 범위(content, marker, markerAndContent 또는 parent)에 적용되는 연산(replace, prepend, append 또는 delete)입니다. 대상은 헤딩(최상위부터 아래로 헤딩 텍스트 배열로 지정), 블록 참조 또는 frontmatter 키입니다. 페이로드는 content(문자열), value(frontmatter 값용 JSON) 또는 destination(헤딩 이동)에 담깁니다:

# Replace the value of a frontmatter field
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"frontmatter","target":"status","operation":"replace","value":"done"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

content 문자열 내부의 헤딩 레벨은 대상에 상대적입니다(앞의 #은 직접 하위 항목이 됩니다). 참고 경고(예: 레벨 6을 넘어 리베이스된 헤딩)는 Markdown-Patch-Warnings 응답 헤더에 퍼센트 인코딩된 JSON으로 반환됩니다. 파싱 전에 decodeURIComponent로 디코딩하세요. 낙관적 동시성을 위해 ifMatch(문서 맵의 version)를 전달하세요.

참고: 공백은 라이브러리가 관리합니다. 콘텐츠는 트리밍된 정규 형식으로 축소되며(앞뒤 빈 줄은 의미가 없음), API가 삽입된 콘텐츠가 본문 텍스트와 마주하는 곳에 빈 줄을 자체적으로 제공하므로 append 또는 prepend는 항상 자체 블록으로 배치되고 기존 단락에 병합되지 않습니다. 헤딩 줄, 기존 빈 줄, 각 문서의 간격 스타일은 그대로 유지됩니다. 실제 예제는 대화형 문서를 참조하세요.

새 블록을 시작하는 대신 기존 블록을 계속하려면(예: 목록 확장) 헤딩 명령에 within을 추가하세요. 섹션의 최상위 본문 블록 중 하나를 선택하는 인덱스입니다(문서 순서 기준 0부터 시작, 끝에서부터 세는 음수, 따라서 -1은 마지막 블록). within 편집은 문자 그대로 접합되므로 연결 지점은 사용자가 관리합니다:

# Add an item to the last list under "Log" (the leading \n continues the block)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["Log"],"within":-1,"operation":"append","content":"\n- new item"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

markerAndContent 범위에서 prepend/append는 대신 인덱스된 블록 옆에 새 블록을 삽입합니다. 인덱스는 위치 기반이므로 먼저 문서 맵을 읽고 편집을 ifMatch와 함께 사용하세요.

원시 콘텐츠 모드

클라이언트가 요청 본문에 마크다운을 템플릿으로 넣는 경우(Shortcuts, Tasker, 템플릿의 curl), 해당 콘텐츠를 명령으로 JSON 이스케이프하는 것은 취약합니다. 원시 콘텐츠 모드는 명령의 필드를 본문 밖으로 이동합니다. 대상은 URL(또는 명시적 Markdown-Patch-Version: 2와 함께 Target-Type/Target 헤더)에, 연산과 옵션은 헤더에 넣고 본문은 원시 페이로드이므로 JSON 이스케이프가 필요 없습니다:

# Append a templated line under a heading — no JSON escaping anywhere
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Operation: append" \
  -H "Content-Type: text/markdown" \
  --data "- $TEMPLATED_CONTENT" \
  https://127.0.0.1:27124/vault/notes/daily.md/heading/Log

text/* 본문은 content 전달자이고, application/json 본문은 value 전달자이며, 본문이 없으면 아무것도 전달하지 않습니다(delete 또는 Destination 헤더를 통한 이동). Target-Scope, Within(명령의 within 인덱스를 일반 정수로, 예: -1), Create-Target-If-Missing, Reject-If-Content-Preexists, If-Match 헤더가 명령을 완성합니다. 헤더 인코딩과 전체 세부 정보는 대화형 문서를 참조하세요.

이미 이전 헤더 기반 PATCH 형식을 사용 중이신가요? 이 형식은 JSON 본문 대신 요청 헤더에 명령을 분산했으며 더 이상 사용되지 않으며 6.0에서 제거될 예정입니다. 여전히 작동합니다. Markdown-Patch-Version: 1을 보내면 다시 사용할 수 있으며(같은 헤더가 GET에서 레거시 ::로 연결된 문서 맵도 선택), 이 형식으로 제공되는 응답에는 Deprecation: true; sunset-version="6.0" 헤더가 포함됩니다. 업그레이드하려면 해당 헤더를 제거하고 각 헤더를 JSON 본문으로 이동하세요. 대화형 문서에 필드별 매핑 테이블이 있습니다.

전체 명령 스키마와 옵션은 대화형 문서를 참조하세요.

특정 섹션 지정

전체 파일을 가져오거나 교체하지 않고도 노트의 특정 부분(헤딩, 블록 참조 또는 frontmatter 필드)을 읽거나 쓸 수 있습니다. GET, PUT, POST, PATCH 요청에서 작동합니다(PATCH의 경우 원시 콘텐츠 모드입니다. Operation 헤더를 추가하세요).

파일 이름 뒤에 /<target-type>/<target>을 추가하세요. 각 중첩 헤딩 레벨은 자체 경로 세그먼트이므로 텍스트에 ::가 포함된 헤딩은 이스케이프가 필요 없습니다:

# Read the content under a specific heading
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Read a nested heading (one path segment per level)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/Work/Meetings

# Read a frontmatter field
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/frontmatter/status

# Replace the content of a heading via PUT (heading levels are normalized for you)
curl -k -X PUT \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Updated content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append to a heading via POST
curl -k -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Appended content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

지원되는 대상 유형: heading, block, frontmatter.

GET에서 Target-Scope 헤더는 PATCH 범위를 반영하여 대상의 어느 부분이 반환될지 선택합니다: content(기본값), marker(레이블 — 헤딩의 원시 텍스트, 블록의 순수 id, frontmatter 키) 또는 markerAndContent(전체 노드, 해당 범위에서 PATCH replace가 사용하는 정확한 형태 — 헤딩 하위 트리는 자체 줄이 # Title로, 레벨은 부모에 상대적으로 읽혀 반환됩니다):

# Read a whole section — heading line included — ready to edit and write back
curl -k -H "Authorization: Bearer <your-api-key>" \
  -H "Target-Scope: markerAndContent" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

더 이상 사용되지 않음: 헤더 기반 대상 지정. 이전 릴리스에서는 Target-Type, Target, Target-Delimiter 헤더(및 Target-Scope/Trim-Target-Whitespace)로 섹션을 지정했습니다. 이 형식은 더 이상 사용되지 않으며 6.0에서 제거될 예정입니다. Markdown-Patch-Version: 1도 함께 보낼 때만 처리됩니다(응답에는 Deprecation 헤더가 포함됩니다). 이 헤더 없이 대상 지정 헤더를 제공하면 400으로 거부됩니다. 하나의 요청에 URL 경로 대상 지정과 헤더 형식을 모두 제공하면 422 Unprocessable Entity가 반환됩니다.

검색

POST /search/simple/?query=your+terms는 Obsidian의 내장 퍼지 검색을 실행하고 점수가 매겨진 컨텍스트 스니펫과 함께 일치하는 파일 이름을 반환합니다.

POST /search/는 JsonLogic 표현식(콘텐츠 유형 application/vnd.olrapi.jsonlogic+json)을 받아 각 노트의 메타데이터(frontmatter, 태그, 경로, 콘텐츠)에 대해 평가합니다.

MCP (Model Context Protocol)

[!NOTE] Obsidian용 타사 MCP 서버가 여러 개 존재하지만, 더 이상 필요하지 않습니다. 이 플러그인은 Obsidian 내부에서 실행되며 볼트의 실시간 메타데이터, 활성 파일, 명령 팔레트에 직접 접근할 수 있는 내장 MCP 서버를 제공합니다. 현재 타사 서버를 사용 중이라면, 이 서버로 전환하는 것이 더 나은 결과를 얻을 가능성이 높습니다.

이 플러그인은 /mcp/에 내장 MCP 서버를 포함하므로 AI 에이전트와 MCP 호환 클라이언트가 HTTP 요청을 직접 작성하지 않고도 볼트와 상호작용할 수 있습니다.

전송 방식: Streamable HTTP — API 키 인증 필요.

프로토콜 개정 버전

이 엔드포인트는 2026-07-28 개정 버전과 2024-10-07부터 2025-11-25까지의 세션 기반 개정 버전을 요청별로 선택하여 제공하므로, 두 방식의 클라이언트가 모두 공유할 수 있습니다.

2026-07-28 개정 버전은 상태 비저장(stateless)입니다. initialize 핸드셰이크도 세션도 없으므로, 플러그인은 Mcp-Session-Id 헤더를 발급하거나 읽지 않습니다. 각 요청은 자체 프로토콜 버전과 클라이언트 ID를 params._meta에 담아 전달하고, 이를 MCP-Protocol-Version, Mcp-Method, Mcp-Name 헤더에 반복하여 각각 독립적으로 응답받습니다. 클라이언트는 server/discover를 호출하여 지원되는 개정 버전과 기능을 미리 확인할 수 있습니다.

initialize 요청으로 시작하는 클라이언트는 협상한 세션 기반 개정 버전으로 서비스됩니다. 핸드셰이크는 Mcp-Session-Id를 반환하고, GET /mcp/는 해당 세션의 알림 스트림을 열며, DELETE /mcp/는 세션을 종료합니다. 세션은 이 경로에서만 존재하며, 핸드셰이크의 listChanged 기능이 정직하게 유지되도록 합니다. 다른 플러그인이 MCP 도구를 등록하거나 제거하면 모든 활성 세션에 알림이 전송되는 반면, 2026-07-28 클라이언트는 subscriptions/listen 스트림을 통해 이를 알게 됩니다.

클라이언트 연결

MCP 클라이언트를 https://127.0.0.1:27124/mcp/에 연결하세요. 인증은 bearer 토큰을 사용합니다. 설정 → Local REST API에서 API 키를 찾은 후 다음과 같이 전달하세요:

Authorization: Bearer <your-api-key>

정확한 구성 구문은 클라이언트마다 다릅니다. 위의 빠른 시작 예시를 참조하거나, Streamable HTTP 원격 MCP 서버에 대한 클라이언트 문서를 확인하세요.

[!WARNING] MCP 서버에 안전하게 연결하려면 클라이언트가 플러그인의 자체 서명 인증서를 신뢰해야 합니다. https://127.0.0.1:27124/obsidian-local-rest-api.crt에서 인증서를 다운로드하여 신뢰할 수 있으며, 또는 127.0.0.1에 대한 TLS 검증을 건너뛰도록 클라이언트를 구성할 수 있습니다.

환경에서 자체 서명 인증서를 신뢰할 수 없는 경우, 설정 → Local REST API → Enable HTTP server에서 HTTP 엔드포인트를 활성화했다면 https://127.0.0.1:27124/mcp/ 대신 http://127.0.0.1:27123/mcp/를 사용하여 안전하지 않게 연결할 수 있습니다.

사용 가능한 도구

사용 가능한 리소스

API 확장

다른 플러그인은 이 플러그인의 서버에 자체 인증 라우트, 공개 라우트 및 MCP 도구를 등록할 수 있습니다. 자세한 내용은 Adding your own API Routes via an Extension을 참조하세요.

타입 기반 확장 API

이 패키지를 개발 의존성으로 설치하면 getAPI와 그 반환 값에 대한 타입을 얻을 수 있습니다:

npm install --save-dev obsidian-local-rest-api

이 패키지는 obsidian, zod, @types/express를 peer dependency로 선언합니다. 그 이유는 이 패키지의 타입이 세 가지 모두를 참조하기 때문입니다. addRoute는 express의 IRoute를 반환하고, addMcpTool은 zod 스키마를 받습니다. npm이 peer dependency를 자동으로 설치해 주지만, 직접 고정(pin)할 경우 해석 가능한 상태로 유지하세요. 그렇지 않으면 TypeScript는 오류를 보고하는 대신 해당 위치를 조용히 any로 확장하므로, 누락된 타입 진단을 억제하는 프로젝트는 가장 중요한 부분에서 타입 검사를 잃었다는 경고를 받지 못하게 됩니다.

import { getAPI, type LocalRestApiPublicApi } from "obsidian-local-rest-api";

const api: LocalRestApiPublicApi | undefined = getAPI(this.app, this.manifest, 2);

패키지 진입점은 작은 독립 모듈입니다. 빌드에 플러그인 번들을 포함하는 대신 Obsidian의 플러그인 레지스트리에서 실행 중인 호스트 플러그인을 해석합니다. 확장 API 버전(위의 2)을 전달하면 설치된 호스트가 필요한 표면보다 오래된 경우 getAPI가 ApiVersionUnsupportedError를 던집니다. 생략하면 설치된 모든 버전을 수용하고 직접 기능을 감지합니다. 플러그인이 설치되지 않았거나 아직 로드되지 않은 경우 getAPI는 undefined를 반환합니다.

publicApi.d.ts는 src/publicApi.ts에서 생성되며, 구현은 컴파일 타임에 이에 대해 검사되므로 게시된 타입이 플러그인이 실제로 제공하는 기능과 어긋날 수 없습니다.

알려진 확장

• Periodic Notes: 주기적 노트 지원 추가

기여

CONTRIBUTING.md를 참조하세요. 핵심을 수정하지 않고 기능을 추가하려면 대신 API 확장을 구축하는 것을 고려하세요. 확장은 독립적으로 개발 및 배포할 수 있습니다.

크레딧

Vinzent03의 advanced-uri 플러그인에서 영감을 받았으며, 사용자 정의 URL 스킴의 제약을 넘어 자동화 옵션을 확장하는 것을 목표로 합니다.