Claude-Atlas-MCP

셀프 호스팅 MCP 서버로, Claude가 대화 간에 지속적인 메모리를 유지할 수 있게 해줍니다 — 엔터티, 관찰, 기록, 시간 지정 알림과 함께, 도착한 항목을 위한 트레이와 아이디어를 위한 선반을 제공합니다. 가벼운 Node/SQLite 백엔드에서 직접 실행하세요.

Claude에 MCP 커넥터로 연결하면, Claude가 대화에서 다음 대화로 넘어갈 때 작업 중인 내용을 기억할 수 있습니다: 진행 중인 프로젝트, 결정과 그 근거, 사용자와 설정에 관한 사실, 그리고 미래 날짜에 다시 표시할 내용 등.

이유

Claude는 대화가 끝나면 모든 것을 잊어버립니다. Atlas는 작고, 지루하며, 내구성 있는 메모리 레이어로, 전적으로 사용자가 소유합니다 — 타사 서비스 없고, 벤더 종속도 없습니다. 하나의 Node 프로세스가 하나의 SQLite 파일로 작동합니다. 홈 서버, VPS, 또는 노트북에서 실행하세요.

의도적으로 비어 있는 상태로 시작합니다. 사용자의 삶에 대한 스키마가 내장되어 있지 않으며, 가정된 직업이나 필수 이슈 트래커도 없습니다 — 사용할 때 채워지는 형태만 있을 뿐입니다.

Related MCP server: memory-mcp

빠른 시작

git clone https://github.com/dcazman/Claude-Atlas-MCP.git
cd Claude-Atlas-MCP
docker compose up -d --build
docker compose logs atlas-mcp

.env 파일, 토큰, 설정이 필요 없습니다. 첫 시작 시 Atlas는 데이터베이스를 생성하고, 각 범위에 대해 하나의 토큰을 생성하여 출력합니다:

    work     3f2a…   (caller "work-client")
    personal 9c41…   (caller "personal-client")
    shared   b7e0…   (caller "shared-client")

  Connect a client to:  http://localhost:7784/atlas-mcp?token=<one of the above>

토큰은 데이터베이스 옆에 저장되며, 재시작할 때마다 재사용됩니다. 데이터는 ./data 디렉토리, 단일 SQLite 파일에 저장됩니다. 이것이 전체 설정입니다.

작동 여부 확인:

curl -s localhost:7784/health
# {"ok":true,"service":"atlas-mcp","version":2,"port":"7784"}

TOKEN=<one of the tokens printed above>
curl -s -X POST localhost:7784/atlas-mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "x-atlas-token: $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":
       {"name":"add_observation","arguments":
        {"section":"work","entity":"Atlas","content":"Installed today."}}}'

observation_id가 반환되면 전체 스택이 작동하는 것입니다: 첫 번째 메모리가 디스크에 저장되었고 Claude가 다시 읽을 수 있습니다.

CI는 main에 푸시될 때마다 이미지를 게시합니다. 직접 빌드하지 않으려면:

docker run -d --name atlas -p 7784:7784 -v "$PWD/atlas-data:/app/data" \
  ghcr.io/dcazman/claude-atlas-mcp:latest
docker logs atlas

순수 Node — 22.13+ 버전이면 내장 node:sqlite를 사용할 수 있습니다. 네이티브 종속성 없음, 컴파일할 것 없음:

npm install
npm start

직접 토큰, 시간대, 또는 정리 시간을 기본값 대신 사용하려면, cp .env.example .env를 실행하고 원하는 줄의 주석을 해제하세요. 편집하지 않고 복사해도 아무 변화가 없습니다 — 모든 줄이 의도적으로 주석 처리되어 있습니다.

데이터 모델

깔때기

세 가지 표면, 약속 수준이 증가하는 순서:

  shelf  ──graduate──▶  tray  ──promote──▶  memory
 (ideas)              (triage)          (observations)

• 선반은 생각난 것들을 보관합니다. 1년 동안 거기에 있는 아이디어가 백로그 실패가 아닙니다 — 선반이 제대로 작동하고 있는 것입니다. 아이디어는 트레이로 승격되거나 의도적으로 폐기될 때 떠나며, 그 이유는 보관됩니다.

• 트레이는 도착한 것들을 보관합니다. 쌓아두는 곳이 아니라 대기열입니다: 캡처한 후 승격, 병합, 또는 해제하세요.

• 메모리는 Claude가 대화 시작 시 다시 읽는 부분입니다.

통과 과정에서 아무것도 파괴되지 않습니다. 해결된 항목은 더 이상 표시되지 않지만, 그 기록(무엇으로 바뀌었는지 포함)은 유지됩니다.

이것들을 실제로 보는 방법. get_landscape는 Claude가 대화 시작 시 호출하는 하나의 호출입니다. 따라서 주의가 필요한 모든 것은 이 안에 다시 나타나야 합니다:

따라서 "지금 캡처하고, 나중에 결정"이 작동합니다: 대화 중간에 트레이에 넣은 것은 다음 대화 시작 시 사용자가 기억하지 않아도 다시 나타납니다.

툴

31개의 MCP 툴.

읽기

• get_landscape — 섹션의 모든 것 (shared가 병합됨): 모든 엔터티와 관찰, 도래한 알림, 분류되지 않은 트레이 항목, 열린 선반 아이디어 개수. 대화 시작 시 호출하여 방향을 잡으세요.

• search — 엔터티, 관찰, 기록에 걸친 키워드 검색.

• get_entity — 이름으로 하나의 엔터티와 그 관찰.

• get_observation — ID로 직접 최대 20개의 관찰을 가져옵니다. ID는 안정적이며 재사용되지 않으므로, 특정 사실을 한 대화에서 다음 대화로 전달하는 저렴한 방법입니다.

• get_history — 기록된 이벤트의 타임라인.

• get_time — 현재 시간과 이 토큰의 마지막 호출 이후 경과 시간.

쓰기

• upsert_entity — 엔터티의 이름/요약을 생성하거나 업데이트.

• add_observation — 엔터티에 사실을 첨부.

• update_observation — 사실을 제자리에서 편집; ID는 안정적. 보호된 행에도 작동.

• remove_observation — 오래되었거나 완료된 사실을 삭제 (보호된 경우 거부).

• protect_observation / unprotect_observation — 사실을 삭제 불가능으로 표시하거나 해제.

• remove_entity — 엔터티와 그 관찰을 삭제 (보호된 것이 있으면 거부).

• log_event — 주목할 만한 이벤트를 기록에 저장.

알림

• create_reminder — trigger_date와 선택적 trigger_time, 선택적 엔터티 링크가 있는 메모.

• list_reminders — 예정된 모든 것, 도래 여부와 관계없이.

• list_due_reminders — 지금 당장 도래한 모든 것. 알리미가 폴링하는 대상입니다.

• mark_reminder_fired — 시간 지정 알림이 전달된 것으로 표시하여 두 번 발사되지 않도록 함.

• dismiss_reminder — 알림이 처리된 것으로 표시 (더 이상 표시되지 않음).

• remove_reminder — 알림을 완전히 삭제.

트레이

• pending_add — 도착한 것을 캡처.

• pending_list — 아직 분류가 필요한 것, 가장 오래된 것부터.

• pending_promote — 캡처를 엔터티의 관찰로 전환.

• pending_merge — 중복을 유지할 것에 접어 넣음.

• pending_dismiss — 필요 없다고 결정, 이유는 보관.

• pending_reopen — 위의 어떤 것이든 되돌림.

선반

• research_add — 아이디어를 보관.

• research_list — 열린 아이디어, 가장 오래된 것부터.

• research_promote — 아이디어를 트레이로 승격.

• research_kill — 의도적으로 아이디어를 폐기, 이유 포함.

• research_reopen — 다시 되돌림.

모든 툴 응답에는 작은 시간 푸터가 포함됩니다 — 설정된 시간대의 현재 서버 시간과 해당 토큰의 마지막 호출 이후 경과 시간 — 따라서 모델이 추측하거나 오래된 정신적 시계로 날짜 계산을 할 필요가 없습니다.

알림 받기

Atlas는 자체적으로 아무것도 푸시하지 않습니다 — 사용자가 어디로 연락받길 원하는지 알 수 없기 때문입니다. 대신, list_due_reminders가 알림을 처리하는 모든 것에 대한 계약입니다:

1. 적절한 간격으로 list_due_reminders를 폴링합니다.

2. trigger_time이 있는 행을 전달합니다 (수동 알림은 랜드스케이프에서 보이는 것만으로 충분합니다).

3. 전달한 각각에 대해 mark_reminder_fired를 호출합니다.

3단계가 정확히 한 번 전달을 보장합니다: 스탬프가 SQL에서 보호되므로, 두 개의 겹치는 폴러가 이중 전송할 수 없습니다. 크론 구동 스크립트 12줄이면 이메일, 채팅 웹훅, 또는 전화 알림에 연결할 수 있습니다.

정리 워커

src/groom.js는 서버 프로세스 내에서 야간에 실행됩니다 (호스트 크론 필요 없음), 또는 npm run groom으로 수동 실행할 수 있습니다. 의도적으로 보고 전용이고 기계적입니다 — LLM 호출이나 데이터 삭제 없음:

• 엔터티 내에서 유사한 중복 관찰을 플래그

• 60일 이상 건드리지 않은 휴면 엔터티를 보관/압축 후보로 플래그

• 오래 해제된 알림 (90일 이상)을 제거 후보로 플래그

• 자체 audit_log (90일 이상)를 회전 — 실제로 삭제하는 유일한 것

• 마지막 실행 이후 건드리지 않은 엔터티는 건너뛰므로 반복 실행이 저렴함

결과는 섹션별 "정리 보고서" 엔터티에 저장되어 사용자(또는 Claude)가 조치를 취할 수 있습니다. ATLAS_GROOM_HOUR (기본값 4시)에 시간대에 맞춰 실행되며, 자가 치유됩니다: 컨테이너가 다운되어 놓친 창은 다음 확인 시 실행됩니다.

Claude 연결하기

Atlas는 스트림 가능한 HTTP를 통해 MCP를 사용하며, POST /atlas-mcp에서 수신합니다. 서버의 URL과 토큰을 사용하여 커넥터로 추가하세요:

https://<your-host>/atlas-mcp?token=<your-secret>

토큰은 ATLAS_TOKEN 삼중 값의 비밀 부분입니다 (설정 참조). 쿼리 문자열 대신 X-Atlas-Token 헤더 또는 Bearer 토큰으로 전달할 수도 있습니다.

URL에 section은 없습니다 — 모든 툴은 section 인수를 받으며, 특정 대화가 기본값으로 사용할 섹션은 Claude 프로젝트의 사용자 지정 명령어에 설정하는 것이 가장 좋습니다 (예: "당신의 Atlas 섹션은 personal입니다"). GET /health 엔드포인트는 활성 상태 확인용으로 제공됩니다.

실제 사용 시에는 HTTPS 뒤에 두는 것이 좋습니다 — 컨테이너 앞에 리버스 프록시 또는 터널(Cloudflare Tunnel, Tailscale, nginx 등)을 두세요. 토큰이 유일한 인증이므로, TLS 없이 포트를 공개적으로 노출하지 마십시오.

연결되면, Claude가 각 대화 시작 시 get_landscape를 호출하고 항목이 변경될 때 업데이트를 유지하는 것이 좋은 습관입니다. 서버는 정확히 그렇게 하라는 지침을 제공하므로, 대부분의 클라이언트는 사용자가 직접 작성하지 않아도 이를 받아들입니다.

보안 유지

Atlas의 내장 인증은 공유 토큰입니다 — 사설 네트워크나 터널 뒤에서는 괜찮지만, 인터넷에 노출하는 경우에는 얇습니다. 실제 접근 제어를 위해서는 이 서버 자체를 강화하는 대신 전용 인증 게이트웨이를 앞에 두세요.

mcp-auth-proxy는 MCP 서버를 위한 드롭인 OAuth 2.1 / OIDC 게이트웨이로, Atlas에 코드 변경이 필요하지 않습니다:

• 자체 IdP(Google, GitHub, Okta, Auth0, Azure AD, Keycloac, 모든 OIDC 제공자)에 대해 인증하며, 선택적 비밀번호를 사용할 수 있습니다.

• 정확히 일치하거나 glob(*@yourcompany.com 등) 방식으로 사용자 인가를 수행합니다.

• TLS를 종료하고 HTTP 전송을 그대로 프록시하며, Claude, Claude Code, ChatGPT, Copilot, Cursor에서 검증되었습니다.

대략적으로 Atlas의 HTTP 엔드포인트를 가리키면 됩니다:

./mcp-auth-proxy \
  --external-url https://<your-domain> \
  --tls-accept-tos \
  -- http://localhost:7784/atlas-mcp

IdP 설정 및 구성에 대한 자세한 내용은 문서를 참조하세요. (제휴 관계는 아닙니다. — 자체 호스팅 MCP 서버에 적합한 도구입니다.)

구성

모두 선택 사항입니다. .env(.env.example 참조) 또는 환경 변수를 통해 설정합니다:

나만의 것으로 만들기

의도적으로 작게 설계되어 있어, 싸우지 않고 확장할 수 있습니다.

• 도구 추가. 모든 것은 src/tools.js에 있으며, 하나의 guarded() 래퍼를 통해 등록됩니다. 이 래퍼는 scope 검사와 감사 로그 기록을 수행합니다. 새 도구는 guarded(name, {description, inputSchema}, handler) 블록과 src/db.js의 함수로 구성됩니다. 설명은 코드보다 더 중요합니다 — Claude가 이를 읽고 도구를 언제 사용할지 결정하기 때문입니다.

• 테이블 추가. 마이그레이션은 src/db.js의 PRAGMA user_version 사다리입니다: 번호를 올리고, 그에 의해 보호되는 추가 SQL을 작성하면 끝입니다. 모든 마이그레이션은 멱등적이며 부팅 시 실행되므로, 업그레이드는 단순히 재시작하면 됩니다.

• 데이터베이스에 규칙 푸시. 여기서의 스타일은 기억해야 하는 규칙은 위반되는 규칙이라는 것입니다. 따라서 resolved_at은 트리거에 의해 기록되며, scope는 서버 측에서 강제 적용되고, 보호된 행은 SQL에서 보호됩니다. 이 패턴을 따르면 추가된 기능도 이를 상속받습니다.

• 섹션 변경. work/personal/shared는 스키마의 CHECK 제약 조건과 src/server.js의 scope 맵에 고정되어 있습니다. 이름을 바꾸는 것은 마이그레이션과 두 줄의 맵 수정으로 가능합니다 — 용어가 본인의 삶에 맞지 않다면 해볼 만한 가치가 있습니다.

테스트

npm test

모든 실행은 빈 데이터베이스에서 시작하므로, 테스트 스위트는 빈 슬레이트 검사 역할도 합니다: 스키마가 처음부터 빌드되고, 토큰 scope 매트릭스가 유지되며(범위 밖의 ID는 존재하지 않는 ID와 구분할 수 없음), 시간 기반 알림이 정확히 한 번만 실행되고, 깔때기가 항목을 주장하는 대로 이동시킵니다.

보안

위협 모델, 배포 강화 노트 및 취약점 신고 방법은 SECURITY.md를 참조하세요.

변경사항

CHANGELOG.md를 참조하세요. 간단히 말하면: v3에서 트레이, 선반, 시간 기반 알림, 관찰 ID 주소 지정, 제로 구성 시작이 추가되었습니다.

라이선스

MIT — LICENSE를 참조하세요.