Obsidian MCP Server 설정 방법 (2026)

Obsidian MCP 서버 설정 방법 (2026)

Obsidian은 수백만 명의 사용자가 로컬 Markdown 파일에 메모, 연구 자료, 개인 위키를 저장하는 가장 인기 있는 지식 관리 도구 중 하나입니다. MCP (Model Context Protocol)를 사용하면 Obsidian 보관함(vault)을 Claude와 같은 AI 어시스턴트에 직접 연결하여, AI가 메모를 읽고, 보관함 전체를 검색하며, 새 메모를 생성하고, 지식 베이스를 컨텍스트에 맞게 활용하도록 할 수 있습니다.

이 가이드에서는 Obsidian MCP 서버를 설정하고 Claude Desktop, Cursor 또는 모든 MCP 호환 클라이언트에 연결하는 방법을 설명합니다.

왜 MCP를 통해 Obsidian을 AI에 연결해야 할까요?

MCP가 없다면 Obsidian 메모를 AI와 함께 사용하기 위해 내용을 채팅창에 수동으로 복사하고 붙여넣어야 합니다. 하지만 MCP를 사용하면 AI가 다음과 같은 작업을 수행할 수 있습니다.

• 키워드, 태그 또는 내용으로 보관함 전체 검색
• 특정 메모 읽기 및 위키 링크, 백링크를 포함한 컨텍스트 이해
• 대화나 연구 내용을 기반으로 새 메모 생성
• 기존 메모를 새로운 정보로 업데이트
• 링크 그래프를 사용하여 메모 간의 연결 분석
• 관련된 여러 메모로부터 요약본 생성

AI는 파편화된 코드 조각이 아닌 귀하의 지식 베이스에 직접 접근하여 작업하게 됩니다.

사전 요구 사항

요구 사항	상세 내용
Obsidian	최신 버전 (보관함은 Markdown 파일 폴더임)
Node.js	v18 이상
MCP 클라이언트	Claude Desktop, Cursor, VS Code 등
npm	MCP 서버 설치용

옵션 1: Obsidian MCP 서버 패키지 사용하기

커뮤니티에서 유지 관리하는 obsidian-mcp-server 패키지는 Obsidian 보관함을 위한 즉시 사용 가능한 MCP 서버를 제공합니다.

1단계: 서버 설치

npm install -g obsidian-mcp-server

2단계: Claude Desktop 설정

Claude Desktop 설정에 서버를 추가합니다.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "obsidian-mcp-server",
        "--vault",
        "/Users/yourname/Documents/MyVault"
      ]
    }
  }
}

경로를 실제 Obsidian 보관함 폴더의 경로로 바꿉니다.

3단계: Claude Desktop 재시작

Claude Desktop을 닫았다가 다시 엽니다. 도구 패널에 Obsidian MCP 서버가 나열된 것을 확인할 수 있습니다.

4단계: 연결 테스트

Claude에게 보관함과 상호작용하도록 요청해 보세요.

"machine learning"에 관한 메모를 내 Obsidian 보관함에서 찾아줘.

내 보관함에서 "Project Ideas"라는 메모를 읽어줘.

우리 대화 내용을 요약해서 내 보관함에 "Meeting Notes 2026-02-06"이라는 새 메모를 만들어줘.

옵션 2: Filesystem MCP 서버 사용하기

전용 Obsidian 패키지 없이 더 간단한 설정을 원한다면, 공식 filesystem MCP 서버를 사용할 수 있습니다. Obsidian 보관함은 결국 Markdown 파일 폴더이기 때문에 직접 작동합니다.

1단계: Filesystem 서버 설정

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents/MyVault"
      ]
    }
  }
}

2단계: 사용하기

filesystem 서버는 AI에게 보관함 디렉터리의 모든 파일에 대한 읽기 및 쓰기 권한을 부여합니다. 이를 통해 다음과 같은 작업이 가능합니다.

• 모든 메모 및 폴더 목록 나열
• 모든 메모 내용 읽기
• 새 Markdown 파일 생성
• 기존 파일 수정
• 파일 이름 검색

전용 Obsidian MCP 서버와 비교했을 때의 단점은 filesystem 서버가 위키 링크([[note]]), 태그, frontmatter 또는 백링크 그래프와 같은 Obsidian 전용 기능을 이해하지 못한다는 점입니다.

옵션 3: 커스텀 Obsidian MCP 서버 구축하기

최대한의 제어를 위해 보관함 구조에 맞춘 커스텀 MCP 서버를 빌드할 수 있습니다. 다음은 TypeScript로 작성된 최소한의 구현 예시입니다.

1단계: 프로젝트 설정

mkdir obsidian-mcp
cd obsidian-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod glob
npm install -D typescript @types/node tsx

2단계: 서버 코드 작성

src/index.ts 파일을 생성합니다.

#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import * as fs from "fs/promises";
import * as path from "path";
import { glob } from "glob";

const VAULT_PATH = process.argv[2] || process.env.OBSIDIAN_VAULT_PATH;

if (!VAULT_PATH) {
  console.error("Usage: obsidian-mcp <vault-path>");
  process.exit(1);
}

const server = new McpServer({
  name: "obsidian-vault",
  version: "1.0.0",
});

// Tool: 내용으로 메모 검색
server.tool(
  "search_notes",
  "Search Obsidian vault notes by content or title",
  {
    query: z.string().describe("Search query (searches titles and content)"),
    limit: z.number().optional().default(10).describe("Max results to return"),
  },
  async ({ query, limit }) => {
    const files = await glob("**/*.md", { cwd: VAULT_PATH });
    const results: { file: string; matches: string[] }[] = [];
    const queryLower = query.toLowerCase();

    for (const file of files) {
      const content = await fs.readFile(
        path.join(VAULT_PATH, file),
        "utf-8"
      );
      const titleMatch = file.toLowerCase().includes(queryLower);
      const lines = content.split("\n");
      const matchingLines = lines.filter((line) =>
        line.toLowerCase().includes(queryLower)
      );

      if (titleMatch || matchingLines.length > 0) {
        results.push({
          file,
          matches: matchingLines.slice(0, 3),
        });
      }

      if (results.length >= limit) break;
    }

    const output = results
      .map(
        (r) =>
          `**${r.file}**\n${r.matches.map((m) => `  > ${m.trim()}`).join("\n")}`
      )
      .join("\n\n");

    return {
      content: [
        {
          type: "text",
          text: results.length > 0 ? output : "No notes found matching your query.",
        },
      ],
    };
  }
);

// Tool: 특정 메모 읽기
server.tool(
  "read_note",
  "Read the full content of an Obsidian note",
  {
    notePath: z
      .string()
      .describe("Path to the note relative to vault root (e.g., 'Projects/my-project.md')"),
  },
  async ({ notePath }) => {
    try {
      const fullPath = path.join(VAULT_PATH, notePath);
      const content = await fs.readFile(fullPath, "utf-8");
      return {
        content: [{ type: "text", text: content }],
      };
    } catch {
      return {
        content: [{ type: "text", text: `Note not found: ${notePath}` }],
        isError: true,
      };
    }
  }
);

// Tool: 새 메모 생성
server.tool(
  "create_note",
  "Create a new note in the Obsidian vault",
  {
    notePath: z
      .string()
      .describe("Path for the new note (e.g., 'Daily/2026-02-06.md')"),
    content: z.string().describe("Markdown content for the note"),
  },
  async ({ notePath, content }) => {
    const fullPath = path.join(VAULT_PATH, notePath);
    const dir = path.dirname(fullPath);

    await fs.mkdir(dir, { recursive: true });
    await fs.writeFile(fullPath, content, "utf-8");

    return {
      content: [{ type: "text", text: `Created note: ${notePath}` }],
    };
  }
);

// Tool: 폴더 내 메모 목록 나열
server.tool(
  "list_notes",
  "List all notes in a vault folder",
  {
    folder: z
      .string()
      .optional()
      .default("")
      .describe("Folder path relative to vault root (empty for root)"),
  },
  async ({ folder }) => {
    const searchPath = path.join(VAULT_PATH, folder);
    const files = await glob("**/*.md", { cwd: searchPath });

    return {
      content: [
        {
          type: "text",
          text:
            files.length > 0
              ? files.map((f) => `- ${f}`).join("\n")
              : "No notes found in this folder.",
        },
      ],
    };
  }
);

// Tool: 메모에서 태그 추출
server.tool(
  "get_tags",
  "Extract all tags from a note or the entire vault",
  {
    notePath: z
      .string()
      .optional()
      .describe("Specific note to get tags from (omit for all vault tags)"),
  },
  async ({ notePath }) => {
    const files = notePath
      ? [notePath]
      : await glob("**/*.md", { cwd: VAULT_PATH });

    const tagSet = new Set<string>();

    for (const file of files) {
      const content = await fs.readFile(
        path.join(VAULT_PATH, file),
        "utf-8"
      );
      const tags = content.match(/#[\w\-\/]+/g);
      if (tags) {
        tags.forEach((tag) => tagSet.add(tag));
      }
    }

    const sorted = Array.from(tagSet).sort();

    return {
      content: [
        {
          type: "text",
          text:
            sorted.length > 0
              ? sorted.join("\n")
              : "No tags found.",
        },
      ],
    };
  }
);

// 서버 시작
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error(`Obsidian MCP server running for vault: ${VAULT_PATH}`);
}

main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});

3단계: 빌드 및 연결

# package.json에 추가
# "type": "module"
# "scripts": { "build": "tsc", "dev": "tsx src/index.ts" }

npx tsc

# 테스트
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | node dist/index.js /보관함/실제/경로

Claude Desktop 설정에 추가:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "/path/to/obsidian-mcp/dist/index.js",
        "/Users/yourname/Documents/MyVault"
      ]
    }
  }
}

실제 활용 사례

연구 어시스턴트

"transformer architecture"에 관한 모든 메모를 보관함에서 찾아보고, 
일치하는 모든 메모의 핵심 통찰력을 결합한 요약 메모를 만들어줘.

일일 메모 생성

Daily 폴더에 오늘(2026-02-06)의 새 일일 메모를 생성해줘. 
오늘 할 일 섹션과 회의록 섹션을 포함하고, 어제 일일 메모와 링크를 걸어줘.

지식 공백 분석

내 보관함의 모든 태그를 나열하고 메모가 3개 미만인 주제를 찾아줘. 
이것들은 내가 더 연구해야 할 잠재적인 지식 공백들이야.

메모 리팩토링

내 "Machine Learning" 메모를 읽고 각 주요 주제별로 별도의 메모로 분리해줘. 
그리고 그 사이에 위키 링크를 생성해줘.

보안 고려 사항

MCP를 통해 Obsidian 보관함을 AI에 연결할 때 다음 사항을 유의하세요.

• AI는 설정된 경로 내의 모든 파일을 읽을 수 있습니다. AI 제공업체의 데이터 처리 정책을 신뢰하지 않는 한 민감한 정보(비밀번호, 금융 데이터, 개인 일기 등)가 포함된 보관함은 연결하지 마세요.
• 쓰기 권한은 AI가 메모를 수정할 수 있음을 의미합니다. 백업을 유지하기 위해 git이나 Obsidian의 내장 버전 히스토리 기능을 사용하세요.
• 범위를 제한하세요. 전체 보관함을 연결하는 대신 AI가 액세스하길 원하는 특정 하위 폴더만 연결하세요.

{
  "mcpServers": {
    "obsidian-work": {
      "command": "npx",
      "args": [
        "obsidian-mcp-server",
        "--vault",
        "/Users/yourname/Documents/MyVault/Work"
      ]
    }
  }
}

문제 해결

"Server failed to start" Node.js v18+이 설치되어 있는지 확인하세요. 터미널에서 명령어를 직접 실행하여 서버를 수동으로 테스트해 보세요.

"Note not found" 오류 보관함 경로가 올바른지, 절대 경로를 사용하는지 확인하세요. Windows에서는 슬래시(/) 또는 이스케이프된 백슬래시(\)를 사용하세요.

보관함이 큰 경우 속도 저하 보관함에 수천 개의 메모가 있는 경우 검색 도구가 느려질 수 있습니다. 콘텐츠 인덱싱 기능을 추가하거나 검색 범위를 특정 폴더로 제한하세요.

Obsidian의 파일 잠금 Obsidian은 파일을 잠그지 않으므로 MCP 서버가 자유롭게 읽고 쓸 수 있습니다. 하지만 MCP 서버가 변경한 사항이 Obsidian에 즉시 나타나지 않을 수 있습니다. Obsidian에서 Ctrl/Cmd+R을 눌러 파일 목록을 새로고침하세요.

마무리하며

MCP를 통해 Obsidian을 AI에 연결하면 정적인 메모 모음이 AI가 쿼리하고 분석하며 확장할 수 있는 동적인 지식 베이스로 바뀝니다. 미리 빌드된 패키지를 사용하든 filesystem 서버를 사용하든 설정에는 약 10분 정도 소요되며, 커스텀 서버 방식을 사용하면 AI가 액세스하고 수행할 수 있는 작업에 대해 완전한 통제권을 가질 수 있습니다.

지식 관리와 함께 이미지, 비디오 또는 말하는 아바타와 같은 AI 생성 미디어가 포함된 프로젝트를 진행하고 계신다면, 이 모든 것을 처리하는 통합 API를 제공하는 Hypereal AI를 확인해 보세요.

Hypereal AI 무료 체험하기 -- 35 크레딧 제공, 신용카드 불필요.