MCP 서버

baram mcp는 명령줄 도구의 명령을 AI 클라이언트에 도구로 내어 줍니다. Claude Code, Claude Desktop처럼 MCP(Model Context Protocol)를 쓰는 클라이언트가 서버를 띄우고, 도구를 불러 노트를 검색하고 읽습니다. 도구는 읽기만 합니다. 볼트의 파일도, 앱의 설정도 바꾸는 도구는 없습니다.

클라이언트에 더하기

서버는 앱의 실행 파일에 mcp를 붙여 실행한 것입니다. macOS에서는 /Applications/Baram.app/Contents/MacOS/baram이고, Linux .deb 패키지에서는 PATH에 있는 baram입니다. Windows에서는 아직 확인하지 않았습니다.

클라이언트가 읽을 볼트는 --vault로 정합니다. 읽는 볼트를 보세요.

Claude Code — 모든 프로젝트에서 쓰도록 한 번 더합니다.

claude mcp add --scope user baram -- /Applications/Baram.app/Contents/MacOS/baram mcp --vault ~/Notes

--scope project를 쓰면 프로젝트의 .mcp.json에 기록되어, 그 프로젝트에서 일하는 모두와 함께 씁니다. 이때 ~/Notes는 셸이 이미 내 홈 폴더 안의 경로로 바꾼 뒤입니다. 따옴표로 감싸 '~/Notes'로 주면 ~가 그대로 남고, 서버가 그것을 실행하는 사람의 홈 폴더로 풉니다. 아니면 모두에게 있는 경로를 주세요.

Claude Desktop — claude_desktop_config.json(macOS에서는 ~/Library/Application Support/Claude/에 있습니다)에 더하고 앱을 다시 시작합니다.

{
  "mcpServers": {
    "baram": {
      "command": "/Applications/Baram.app/Contents/MacOS/baram",
      "args": ["mcp", "--vault", "/Users/you/Notes"]
    }
  }
}

읽는 볼트

• --vault를 주지 않으면 앱에 등록된 볼트와 폴더가 모두 클라이언트에 열립니다. 이때 기본값은 Claude Code가 서버에 알려 주는 프로젝트 디렉터리를 담은 등록 볼트나 폴더이고, 그런 것이 없으면 서버가 시작된 디렉터리를 담은 등록 볼트나 폴더입니다. 프로젝트 폴더 안에 있는 볼트는 프로젝트 디렉터리를 담지 않으므로 그것으로는 골라지지 않습니다. 기본값으로 읽으려면 --vault를 주세요.
• --vault를 주면 도구는 지정한 볼트만 읽습니다. 볼트마다 한 번씩 주고, 첫 번째가 기본값입니다. 절대 경로이거나, ~ 하나이거나, ~/(Windows에서는 ~\도)로 시작하는 값은 경로이고, 그 폴더는 앱에 등록되어 있지 않아도 됩니다. 그 밖의 값은 .notes와 ~notes를 포함해 등록된 볼트나 폴더의 이름 또는 별칭입니다.
• 도구마다 vault 인자로 이 가운데 하나를 이름이나 별칭, 또는 같은 꼴의 경로로 고릅니다. 이 밖의 볼트는 고를 수 없고, 존재하지 않는 경로도 이 밖의 경로와 같은 답을 받습니다.
• 볼트는 호출할 때마다 다시 읽습니다. 앱에서 볼트를 등록하거나, 이름을 바꾸거나, 제거하면 다음 호출에 반영됩니다. --vault를 준 경우에는 폴더는 지정한 그대로이지만, 앱이 그 폴더를 부르는 것은 다시 읽습니다. 앱에서 바꾼 이름이나 별칭은 다음 호출에 반영되고, 앱이 더는 등록하지 않는 폴더는 unregistered로 나옵니다.

--vault로 볼트를 고르지 못하면(예를 들어 그 경로에 폴더가 없거나, 그 이름을 가진 볼트가 없거나 두 볼트가 그 이름을 함께 쓰면) 서버는 클라이언트와 연결되기 전에 멈추고, 이유를 표준 오류에 씁니다. Claude Desktop은 그것을 서버마다 로그로 남깁니다. macOS에서는 ~/Library/Logs/Claude/mcp-server-baram.log입니다.

도구

도구	돌려주는 것	명령
list_vaults	서버가 읽는 볼트와, 호출이 읽는 볼트	vaults
list_files	볼트나 한 폴더의 노트	files
read_note	노트 하나의 본문	read
search	텍스트나 정규식에 맞는 줄	search
list_tags	태그와 각 태그가 나온 횟수	tags
notes_with_tag	태그가 붙은 노트	tag
list_tasks	상태별 또는 노트 하나의 태스크	tasks
backlinks	노트를 가리키는 링크	backlinks
outgoing_links	노트에 든 링크와 각 링크가 가는 곳	links

각 도구의 설명과 인자는 모델이 읽도록 쓴 것이고, 클라이언트가 그것을 모델에 전합니다. 도구가 돌려주는 행은 명령의 --json 출력의 행과 같습니다. 다만 list_vaults는 앱에 등록되지 않은 --vault도 unregistered 유형으로 보여 줍니다.

페이지

목록을 돌려주는 도구는 list_vaults만 빼고 결과를 한 페이지씩 돌려줍니다. items와 함께, 뒤에 더 있으면 truncated가 참이고, 다음 페이지를 요청하는 offset이 nextOffset으로 옵니다. limit의 기본값과 최댓값은 이 도구마다 정해져 있고, 도구의 인자에 나옵니다.

read_note도 같은 방식으로 노트를 줄 단위로 나눕니다. offset은 건너뛸 줄 수이므로, search가 12번째 줄에서 찾은 곳부터 읽으려면 offset: 11을 줍니다. 긴 노트의 페이지는 줄 끝에서 일찍 끝나기도 합니다.

두 호출 사이에 볼트가 바뀌면 다음 페이지가 밀릴 수 있습니다.

명령줄 도구와 다른 점

• read_note는 노트만 읽습니다. list_files가 보여 주는 .md와 .markdown 파일, 곧 앱이 태그 · 태스크 · 링크를 찾으려고 훑는 파일입니다. 숨김 파일, 숨김 폴더나 node_modules 안의 파일, 그 밖의 모든 파일은 거부합니다. 명령줄의 read는 숨김 파일을 포함해 볼트 안의 텍스트 파일이면 무엇이든 읽습니다.
• search는 일반 폴더 안의 숨김 .md 파일도 읽습니다. notes/.draft.md 같은 파일이고, 명령과 같은 동작입니다. 그런 파일은 read_note로 열 수 없습니다.
• backlinks는 명령과 같이 아직 없는 노트도 받고, 경로가 폴더이면 거부합니다. 서버가 읽는 볼트 안에서는 도구는 경로가 있는지를 숨기지 않습니다. 파일이나 폴더가 있을 때와 없을 때 오류가 다를 수 있습니다. 예를 들어 backlinks는 없는 노트에는 답하지만 폴더는 거부하고, read_note는 노트가 아닌 파일을 없는 파일과 다른 오류로 거부합니다. 심볼릭 링크를 지나 볼트 폴더로 풀리는 vault 인자나, 링크를 지나 볼트 안으로 풀리는 경로 인자는 받아들이므로, 그 링크가 있는지도 드러납니다. 오류가 파일의 내용을 보여 주지는 않습니다.
• .으로 시작하는 vault는 경로가 아니라 이름입니다. .notes는 앱이 그 이름으로 보여 주는 볼트입니다. 상대 경로는 받지 않습니다. 서버를 어느 디렉터리에서 시작하는지 알려 주지 않는 클라이언트도 있기 때문입니다.
• 오류는 명령줄 도구와 같습니다. 실패한 도구는 error[CODE]: 메시지를 돌려주고, 코드도 같습니다. 서버에 없는 도구를 부르면 그 대신 프로토콜 오류이고, JSON이 아닌 줄에는 답하지 않습니다.