옵시디언 Omnisearch를 Claude 데스크탑에서 활용: MCP 서버 개발 기록

Claude 데스크탑에서 옵시디언 노트를 활용할 수 있도록, 옵시디언 Omnisearch 플러그인과 연동 가능한 MCP 서버를 직접 개발했습니다.
 
이 글에서는 개발 과정을 기록하여 공유하고자 합니다.
 

---

 
기존 옵시디언 노트를 검색할 수 있는 공개 MCP 서버가 몇 가지 존재하지만, 파일명 기반 검색에 한정되거나 설정 과정이 복잡하여 실사용에 한계가 있었습니다. 이러한 문제를 해결하기 위해, Omnisearch 플러그인의 강력한 검색 API를 활용하여 정교한 검색이 가능한 MCP 서버를 구축하게 되었습니다.
 
참고할 만한 기존 MCP 서버

• calclavia/mcp-obsidian : Claude Desktop에서 마크다운 노트를 포함한 디렉토리(Obsidian 볼트)를 읽고 검색할 수 있도록 지원하는 MCP 서버입니다.
• MarkusPfundstein/mcp-obsidian : 옵시디언 REST API 플러그인을 통해 옵시디언과 상호 작용할 수 있는 MCP 서버입니다.

---

 
이제부터는 Omnisearch API 연동을 통해 MCP 서버를 구축한 과정을 자세히 살펴보겠습니다! 🚀
 

개발을 시작하기 전에

레딧에서 이 트릭을 참고하면 개발에 큰 도움이 됩니다.
 
MCP 서버를 개발하기 위해 필요한 라이브러리를 먼저 설치해야 합니다.
 
맥OS 기준 설치 방법은 다음과 같습니다: 설치 가이드 참고
 
MacOS 사전 설치

brew install uv git sqlite3

 

MCP 서버 개발 과정

이번 프로젝트에서는 fastmcp 프레임워크를 사용했습니다.
 

1. 프로젝트 생성

mkdir mcp-server-onmisearch
cd mcp-server-onmisearch
uv init

 

2. fastmcp 패키지 설치

uv add fastmcp

 

3. 코드 작성

아래는 옵시디언 노트를 검색하는 MCP 서버 코드입니다.

from fastmcp import FastMCP
from urllib.parse import quote
import requests 


mcp = FastMCP("obsidian-omnisearch")


@mcp.tool()
async def obsidian_notes_search(query: str) -> list[str]:
    """Search Obsidian notes"""
    try:
        search_url: str = "http://localhost:51361/search?q={query}"
        response = requests.get(search_url.format(query=quote(query)))
        response.raise_for_status()
        return response.json()
    except Exception as e:
        print(f"Error: {e}")
        return []

 

4. 테스트하기

아래 명령어를 사용해 로컬 서버에서 개발 테스트를 진행합니다.

uv run fastmcp dev server.py

 

5. 설치하기

MCP 서버를 Claude 데스크탑 설치하려면 다음 명령을 실행합니다.

uv run fastmcp install server.py

 

설치 후, /Users/[username]/Library/Application Support/Claude/claude_desktop_config.json 파일에 아래와 같은 내용이 추가됩니다. 디렉토리 경로는 본인 환경에 맞게 수정합니다.

{
  "mcpServers": {
    "Omnisearch": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-server-omnisearch",
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

 

6. 사용하기

Claude 데스크탑에 연결된 MCP 서버를 통해 옵시디언 노트를 검색해 사용할 수 있습니다.

 

문제 해결 팁

개발 중 발생하는 문제는 modelcontextprotocol/servers 리포지토리의 이슈 페이지를 참고하면 대부분 해결할 수 있습니다.
특히 비슷한 에러 로그가 자주 있어, 큰 도움이 됩니다.
 

---

이 글이 도움이 되길 바랍니다! 😊
 
 

제가 작성한 소스 코드는 모두 공개되어있습니다.
https://github.com/anpigon/mcp-server-obsidian-omnisearch