MCP로 Claude Code를 암호화 지식 베이스에 연결하기

Knowtarium은 사람과 각자의 AI 에이전트가 함께 일하는 종단간 암호화 지식 베이스예요. Claude Code는 내 컴퓨터에서 실행되며 그곳에서 노트를 복호화하는 작은 서버를 통해 MCP로 연결돼요. 연결되면 Claude Code는 다음을 할 수 있어요.

• 노트를 검색하고 읽어요. 내가 허락한 워크스페이스와 폴더 안에서 노트 사이의 링크를 따라가고 관련 노트를 찾아요.
• 노트를 만들고 편집해요. 각 변경은 즉시 저장되고, Claude Code 자신의 키로 서명되며, 기록에 남아요. 그래서 무엇을 했는지 보고 클릭 한 번으로 되돌릴 수 있어요.
• 폴더 지침을 따라요. 앱에서 워크스페이스나 폴더에 쓴 지침(그 AGENTS.md)은 Claude Code가 그곳에서 읽고 쓸 때마다 전달돼요. Claude Code는 이 지침에 대해 변경을 제안만 할 수 있고, 직접 바꿀 수는 없어요.
• 원하는 곳에서는 나를 기다려요. 워크스페이스나 폴더에 검토("Ask me first")를 켜면, 그곳에서 Claude Code의 노트 변경은 내가 승인하거나 거절할 diff로 대기해요. 그곳에서 폴더 변경은 대신 거부되고, Claude Code가 무엇을 바꾸려 했는지 알려 줘요.
• 노트를 이동하거나 삭제하고 폴더를 바꿔요. 단, 그 권한을 준 경우에만 가능하고, 대화에서 내가 요청할 때만 하도록 안내받아요.

허락하지 않은 워크스페이스나 폴더에 접근하거나, 내 이름으로 서명하거나, 노트를 내가 확인한 것으로 표시하거나, 검토를 켠 곳에서 검토를 건너뛸 수는 없어요. 전체 목록은 에이전트 페이지에 있어요.

Node.js 20 이상(22 또는 24 권장)과 무료 Knowtarium 계정이 필요해요. 터미널을 열고 홈 폴더에서 명령을 실행하세요. npx는 실행되는 폴더를 신뢰하므로, 프로젝트 안에서 실행하면 그 프로젝트의 파일이 Knowtarium의 파일을 대신할 수 있어요.

$ cd ~                          # 프로젝트가 아닌 홈 폴더$ npx knowtarium connect
Opening the browser to connect this computer to Knowtarium.
Connected to workspace ws_8f2k (read and write).
Add Knowtarium to which agents? Claude Code
added to Claude Code (/Users/you/.claude.json)
  previous file saved as /Users/you/.claude.json.knowtarium-backup-<time>

1. 이 컴퓨터를 승인하세요. 브라우저에서 Knowtarium이 열려요. 에이전트 이름을 정하고, 접근할 수 있는 범위를 고른 뒤(아래 참고) Allow를 클릭하세요. 단, 직접 명령을 실행한 경우에만요. 브라우저가 터미널에 닿을 수 없는 SSH 환경에서는 대신 양쪽에 표시되는 일치하는 코드를 확인해요.
2. 에이전트를 고르세요. CLI가 컴퓨터에서 찾은 에이전트를 모두 체크된 상태로 보여 줘요. Enter를 누르면 전부에 Knowtarium을 추가하고, 먼저 일부를 해제할 수도 있어요(화살표로 이동, 스페이스로 선택·해제, a로 전체 선택·해제, Esc는 아무것도 추가하지 않음).
3. Claude Code에 항목이 추가돼요. CLI는 ~/.claude.json(설정했다면 $CLAUDE_CONFIG_DIR 안)에 있는 Claude Code의 사용자 설정에 Knowtarium을 추가해요. 다른 서버와 설정은 그대로 두고, 이전 파일은 그 옆에 백업해요. 이 항목은 Claude Code가 열어 둔 프로젝트가 아니라 항상 홈 폴더에서 서버를 시작해요.
4. Claude Code를 다시 시작하세요. Claude Code는 시작할 때 새 서버를 불러오므로, 이미 실행 중이던 세션은 종료하고 다시 시작하세요.

Claude Code의 설정에는 비밀번호, 토큰, 키가 들어가지 않아요. 연결은 암호화되어 저장되고, 그 키는 시스템 키체인(키체인이 없으면 나만 읽을 수 있는 파일)에 보관돼요. CLI가 무엇이든 쓰기 전에 무엇을 바꿀지 보려면 npx knowtarium agents --dry-run을 실행하세요. CLI는 오픈 소스이고, 코드는 GitHub에 있어요.

(새 탭에서 원래 크기로 열림) (새 탭에서 원래 크기로 열림)

Knowtarium 플러그인에는 테스트된 knowtarium 릴리스에 고정된 같은 MCP 서버와, Knowtarium 워크스페이스에서 일하기 위한 스킬(knowtarium-conventions)이 들어 있어요. 플러그인도 Node.js 20 이상이 필요하고, 런처는 홈 폴더에서 서버를 시작해요. Claude Code에서:

/plugin marketplace add Knowtarium/knowtarium-plugins/plugin install knowtarium@knowtarium

Claude Code 2.1.275 이상에서는 한 줄로 둘 다 할 수 있어요.

/plugin install knowtarium --marketplace Knowtarium/knowtarium-plugins

셸에서는 Claude Code 2.1.292 이상에서:

$ claude plugin install knowtarium --marketplace Knowtarium/knowtarium-plugins

그런 다음 이 컴퓨터를 한 번 연결하세요. Claude에게 Knowtarium을 연결해 달라고 하면 브라우저가 열려 이 컴퓨터를 승인할 수 있어요. 또는 홈 폴더에서 --no-agents와 함께 명령을 실행하세요. 플러그인이 이미 서버를 실행하므로, 이 플래그가 없으면 명령이 서버를 하나 더 추가해요.

$ cd ~$ npx knowtarium connect --no-agents

플러그인과 연결 명령, 무엇을 쓸까요?

어느 쪽이든 Claude Code는 같은 도구와 같은 규칙을 받아요. 하나만 고르세요. Claude Code에 이미 플러그인이 있으면 명령은 Claude Code를 체크 해제된 상태로 두어 서버가 두 번 실행되지 않게 해요. 명령을 먼저 실행하고 나중에 플러그인을 설치했다면 CLI가 자기 항목을 계속 업데이트하므로 서버가 하나 더 실행돼요. 플러그인의 서버만 남기려면 claude mcp remove --scope user knowtarium을 실행하세요.

명령이 여는 페이지에서 이 연결이 할 수 있는 일이 정해져요. 모든 것은 이 에이전트 하나에만 적용되고, 서버가 이를 강제해요.

• 워크스페이스 하나. 각 연결은 정확히 하나의 워크스페이스에 접근해요. Claude Code에 다른 워크스페이스를 주려면 npx knowtarium connect를 다시 실행하고, 다른 워크스페이스를 고른 뒤 Claude Code를 다시 시작하세요. 첫 번째 연결은 그대로 남아요.
• 원하면 일부 폴더만. 필요한 폴더만 체크하세요. 그 위에 있는 폴더의 지침도 읽지만, 그 지침에 대한 변경은 제안할 수 없어요.
• 읽기 또는 읽기·쓰기. 노트에서 답만 얻고 싶다면 읽기 전용으로 시작하세요.
• 편집 이상의 일은 체크할 때만. 노트 이동, 노트 삭제, 폴더 만들기, 이름 바꾸기, 이동, 삭제는 여섯 가지 별도 권한이고, 모두 기본값은 꺼짐이에요.

나중에 앱의 Settings, Agents에서 모두 바꿀 수 있으며, 바꿀 때마다 새 권한 세트에 서명해요. 그곳에서 Claude Code의 접근을 취소하면 즉시 차단되고 워크스페이스는 새 키를 받으므로, 그 이후에 쓰인 것은 읽을 수 없어요. 터미널에서는 npx knowtarium disconnect가 이 컴퓨터의 접근 권한을 해지하고 로컬 키와 캐시를 삭제해요.

Claude Code에는 이미 메모리가 있어요. 내가 쓰고 모든 세션에서 불러오는 CLAUDE.md, 그리고 Claude Code가 직접 쓰고 한 컴퓨터에만 남는 자동 메모리예요. 둘 다 프로젝트에서 어떻게 일할지 담기에 좋아요. 하지만 결정, 리서치, 회의 메모, 여러 에이전트와 사람이 의지하는 사실 같은 지식 자체를 담기에는 둘 다 적합하지 않아요.

그게 지식 베이스가 있는 이유예요. 프로젝트 규칙은 CLAUDE.md에 두고, Claude Code가 알게 된 것은 Knowtarium에서 찾아보고 기록하게 하세요. 그러면 연결한 다른 모든 에이전트도 같은 노트를 봐요. 저희의 Claude Code 세컨드 브레인 가이드에서 CLAUDE.md와 자동 메모리를 자세히 다뤄요.

특별한 명령은 필요 없어요. 평소 말로 요청하면 Claude Code가 도구를 골라요. 다음은 읽기 전용부터 작고 구체적인 편집까지, 처음 해 보기 좋은 프롬프트예요.

> 내 Knowtarium 워크스페이스에서 뭘 할 수 있나요?
 
> 내 노트에서 가격 결정을 찾아서, 참고한 노트의 링크와
  함께 답해 주세요.
 
> meetings 폴더를 읽고 이번 주 요약을 새 노트로
  써 주세요. 회의 노트는 바꾸지 마세요.
 
> 오늘 통화 메모를 Acme 프로젝트 노트에 추가해 주세요.
  그 밖에는 아무것도 바꾸지 마세요.
 
> 내 인박스에 뭐가 있나요?
  클립마다 할 일을 하나씩 제안해 주세요.

첫 번째 프롬프트는 연결이 작동하는지 빠르게 확인하는 방법이에요. Claude Code는 보통 워크스페이스 이름을 말하고, 변경이 즉시 저장되는지 승인을 기다리는지 알려 줘요. 마지막 프롬프트는 웹 클리퍼로 저장한 클립을 읽어요. 처음 편집은 범위를 좁게 하고, 바뀌면 안 되는 것을 말해 주세요. 바뀐 노트 마흔 개보다 네 개를 검토하는 게 훨씬 쉬워요.

Claude Code의 모든 변경은 자신의 키로 서명되므로, 어떤 편집이 Claude Code의 것인지 항상 알 수 있어요.

• 사이드바의 점이 Claude Code가 편집한 노트를 열어 볼 때까지 표시하고, 워크스페이스 페이지는 그 노트들을 Edited by agents 아래에 나열해요.
• 노트 제목 아래 줄에 Claude Code가 편집했다고 표시되고, diff를 보는 See changes와 이전 버전을 되살리는 Undo가 있어요.
• 삭제, 이동, 폴더 변경은 워크스페이스 페이지의 Deleted and reorganized by agents 아래에 2주 동안(기록 보관 기간이 더 짧으면 그 기간 동안) Undo, Undo this agent's last 24 hours와 함께 나열돼요. 삭제된 노트는 기록 보관 기간 안이라면 되살릴 수 있어요.
• 기록은 하루에서 1년까지 내가 정한 기간 동안 모든 버전을 보관해요. 검토가 켜진 폴더에서는 변경이 대신 검토 대기열에서 기다려요.

(새 탭에서 원래 크기로 열림) (새 탭에서 원래 크기로 열림)

에이전트 편집 검토 가이드에는 에이전트가 바꾼 것을 믿기 전에 확인하는 루틴이 있어요.

Claude Code에서 Knowtarium이 보이지 않아요

Knowtarium을 추가한 뒤 Claude Code를 다시 시작하세요. 이미 실행 중이던 세션은 새 서버를 불러오지 않아요. 플러그인을 썼다면 /plugin에서 설치되어 있고 켜져 있는지 확인하세요.

연결 확인하기

npx knowtarium status는 연결된 워크스페이스와 그 접근 권한, 변경 방식, 토큰, 로컬 캐시를 보여 주고, 키가 어디에 보관되는지 알려 줘요.

knowtarium이 업데이트하라고 해요

홈 폴더에서 npx knowtarium@latest agents를 실행하세요. 에이전트가 새 버전을 가리키게 해요. 그런 다음 Claude Code를 다시 시작하세요. 플러그인을 쓴다면 Claude Code에서 마켓플레이스를 업데이트한 다음 플러그인을 업데이트하고(/plugin marketplace update knowtarium, 그다음 /plugin에서 Update now) 다시 시작하세요.

$ cd ~$ npx knowtarium@latest agents$ npx knowtarium status

저장될 줄 알았던 변경이 승인을 기다려요

Claude Code는 각 변경이 저장되었는지 제안되었는지, 그리고 그 이유를 알려 줘요. 폴더가 검토를 요구하거나, 워크스페이스 설정을 확인할 수 없었거나, 오늘의 직접 변경 한도에 도달했거나, 이 연결이 제안만 할 수 있는 경우예요. 마지막 경우라면 홈 폴더에서 npx knowtarium connect를 다시 실행한 뒤 Claude Code를 다시 시작하세요.

Windows에서는

위에서 설명한 대로 플러그인 대신 홈 폴더에서 npx knowtarium connect(또는 npx knowtarium agents)를 쓰세요.