cursor-chats-bridge

Claude Code가 Cursor에서 수행 중인 작업을 실시간으로, 그리고 세션 전반에 걸쳐 확인할 수 있게 해주는 읽기 전용 브리지입니다.

Claude Code와 Cursor를 병행하여 사용하는 경우(예: Claude로 계획/감사하면서 Cursor에서 에이전트 기반 편집 수행)에 이 스킬은 Cursor의 로컬 채팅 데이터베이스를 MCP 서버로 Claude에 연결합니다. 또한 5분마다 새로운 메시지를 저널링하여 Claude가 실행 중이지 않았을 때에도 *"오늘 아침에 Cursor에서 무엇을 했지?"*와 같은 질문에 답할 수 있게 합니다.

설계상 읽기 전용입니다. Cursor의 데이터를 절대 수정하지 않습니다.

제공 기능

설치 후 Claude Code는 7개의 도구(mcp__cursor-chats__ 접두사 포함)를 얻게 됩니다:

또한 5분마다 실행되는 Windows 예약 작업 ClaudeCursorChatPoller가 각 워크스페이스의 활성 채팅에서 새로운 메시지를 감지하여 ~/.claude/mcp/cursor-chats/journal.ndjson 아래의 JSON-lines 저널에 추가합니다.

Related MCP server: cursor-history-mcp

존재 이유

Cursor의 채팅 데이터는 로컬 SQLite KV 저장소(%APPDATA%\Cursor\User\globalStorage\state.vscdb)에 저장되지만, 두 가지 제약 사항이 있습니다:

1. 워크스페이스당 현재 열려 있는 채팅만 메시지가 로컬에 저장되며, 이전 채팅은 Cursor 클라우드로 아카이브되어 메타데이터만 남습니다.

2. 공개 API가 없습니다.

따라서 실시간 MCP 쿼리만으로는 충분하지 않습니다. 오후 3시에 "오늘 아침에 Cursor에서 무엇을 했지?"라고 물어보면 관련 메시지는 이미 아카이브되었을 수 있습니다. 폴러는 메시지가 나타날 때마다 캡처하여 이를 해결하며, 워크스페이스 태깅을 통해 다양한 Claude 프로젝트가 깔끔하게 필터링할 수 있도록 합니다.

아키텍처

┌──────────────────────────────────────────────────────────────────┐
│  Windows Task Scheduler  >>  pythonw poller.py  >>  /5 min, 24/7│
└──────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼ (read mode=ro,immutable=1)
              ┌──────────────────────────────────┐
              │  Cursor SQLite globalStorage     │ ← live, written by Cursor
              │  state.vscdb / cursorDiskKV      │
              └──────────────────┬───────────────┘
                                 │
                                 ▼ (append-only)
              ┌──────────────────────────────────┐
              │  ~/.claude/mcp/cursor-chats/     │
              │   ├─ active_snapshot.json        │
              │   ├─ journal.ndjson              │
              │   └─ poller.log     (errors)     │
              └──────────────────┬───────────────┘
                                 │
                                 ▼ (on-demand)
              ┌──────────────────────────────────┐
              │   MCP server (server.py)         │
              │   exposes 7 tools                │
              └──────────────────┬───────────────┘
                                 │
                                 ▼
                            Claude Code

더 자세한 내부 구조(SQLite 키 패턴, 워크스페이스 식별, 엣지 케이스)는 references/architecture.md를 참조하세요.

요구 사항

• Windows 10 / 11 (Linux/macOS는 아직 지원되지 않음 — schtasks 및 Windows Cursor 경로 사용)

• pythonw.exe를 사용할 수 있는 Python 3.10+ (예약 작업을 위한 백그라운드 실행기)

• PATH에 있는 Claude Code CLI (claude --version이 작동해야 함)

• Cursor 설치 및 최소 1회 실행 (SQLite는 첫 실행 시 생성됨)

설치 프로그램은 이 모든 항목을 확인하며 누락된 항목이 있으면 즉시 실행 가능한 오류 메시지를 표시합니다.

설치

Claude Code 스킬로 설치 (권장)

1. 폴더를 Claude Code 스킬 디렉터리에 넣습니다:

   ~/.claude/skills/cursor-chats-bridge/

   Windows의 경우: C:\Users\<사용자>\.claude\skills\cursor-chats-bridge\.

2. Claude Code를 다시 시작합니다(또는 새 세션을 엽니다).

3. Claude에게 "install the cursor-chats bridge" 또는 *"set up the Claude-Cursor connection"*과 같이 요청합니다. 스킬 설명은 해당 문구에 반응하도록 조정되어 있습니다.

4. Claude가 SKILL.md를 읽고 scripts/install.ps1을 실행한 후 결과를 보고합니다.

5. Claude Desktop을 다시 시작(시스템 트레이에서 완전히 종료)하여 MCP 서버를 로드합니다.

수동 설치 (Claude 필요 없음)

에이전트 단계를 건너뛰려면:

powershell -ExecutionPolicy Bypass -File "C:\Users\<you>\.claude\skills\cursor-chats-bridge\scripts\install.ps1"

스크립트 수행 작업:

1. 필수 구성 요소(Python, pythonw.exe, claude CLI, Cursor SQLite 경로) 확인

2. server.py 및 poller.py를 ~/.claude/mcp/cursor-chats/로 복사

3. 누락된 경우 pip를 통해 Python mcp 패키지 설치

4. 이전 cursor-chats MCP 등록을 제거한 후 새로 추가(기본 범위: local)

5. ClaudeCursorChatPoller 예약 작업 생성/업데이트(5분마다, pythonw.exe를 통해 조용히 실행)

6. 스냅샷/저널을 시드하기 위해 폴러를 한 번 실행

재실행은 안전합니다. 모든 단계에서 강제 덮어쓰기 의미론을 사용합니다. 상태 파일(active_snapshot.json, journal.ndjson)은 보존됩니다.

설치 프로그램 플래그

확인

설치 및 Claude 재시작 후:

claude mcp list
schtasks /Query /TN ClaudeCursorChatPoller /FO LIST

둘 다 항목이 표시되어야 하며, claude mcp list 줄은 cursor-chats에 대해 ✓ Connected를 보고해야 합니다.

Claude 세션에서 다음과 같이 질문할 수 있습니다:

*"List my Cursor workspaces." *"What's the latest message from my Cursor agent?" *"Summarize what I did with Cursor this morning."

Claude의 사용 방식 (일반적인 패턴)

MCP는 자체적으로 폴링하지 않습니다. Claude는 필요할 때 도구를 호출합니다. 백그라운드 폴러(별도 프로세스)가 지속적인 캡처를 처리하므로, 저널 쿼리는 라이브 대화를 열어두지 않고도 "당신이 보고 있지 않을 때 무슨 일이 일어났는지"에 답할 수 있습니다.

예시:

• 이어하기 — *"continue what I was doing with Cursor" → Claude가 get_active_chat을 호출하여 실시간 대화를 가져오고 요약한 뒤, 어디서부터 이어갈지 묻습니다.

• 요약 — *"recap of my Cursor activity since 9 AM" → Claude가 get_journal_summary(window_minutes=N)을 호출하여 변경된 내용을 안내합니다.

• 교차 검증 — *"is what Cursor is suggesting consistent with our plan?" → Claude가 최신 Cursor 메시지를 읽고 자체 컨텍스트와 비교하여 불일치 사항을 표시합니다.

• 검색 — *"where did I discuss the SQL backfill with Cursor?" → Claude가 search_chats("backfill")을 호출한 다음 get_chat으로 결과를 자세히 확인합니다.

개인정보 보호 및 보안

• SQLite 강제 읽기 전용 (mode=ro,immutable=1). 버그가 있는 스크립트라도 Cursor의 데이터를 수정할 수 없습니다.

• 모든 데이터는 로컬에 유지됩니다. 저널과 스냅샷은 사용자 프로필 수준에서 Windows ACL로 보호되는 ~/.claude/ 아래에 있습니다. 아무것도 업로드되지 않습니다.

• 자격 증명 주의사항. Cursor 채팅에는 붙여넣은 API 키, 비밀번호 등이 포함될 수 있습니다. 저널은 메시지 텍스트를 그대로 저장합니다. 이것이 우려된다면 Cursor에 붙여넣는 내용을 선택적으로 하거나, 저널을 사후 필터링하세요.

• MCP 범위. 기본값 local은 설치 프로그램을 실행한 프로젝트에서만 브리지가 활성화됨을 의미합니다. 전역으로 만들려면 -Scope user를 사용하세요.

제거

powershell -ExecutionPolicy Bypass -File "<skill-dir>\scripts\uninstall.ps1"

예약 작업을 제거하고 Claude에서 MCP 등록을 해제하며 기본적으로 ~/.claude/mcp/cursor-chats/를 삭제합니다. active_snapshot.json 및 journal.ndjson을 보존하려면 -KeepData를 전달하세요.

제한 사항 및 알려진 문제

• Windows 전용. macOS/Linux 변형도 가능하지만(schtasks 대신 cron, macOS의 경우 ~/Library/Application Support/Cursor/... 경로) 아직 구현되지 않았습니다.

• Cursor 스키마 의존성. 이 브리지는 문서화되지 않은 Cursor 내부 구조를 읽습니다. Cursor가 cursorDiskKV의 이름을 변경하거나 버전 간에 composer JSON 형태를 변경하면 스크립트에 한 줄 패치가 필요할 수 있습니다. 저널이 증가하지 않으면 poller.log를 확인하세요.

• 활성 채팅만 가능. 이전/아카이브된 채팅은 메타데이터만 제공합니다. 실시간 메시지는 워크스페이스당 현재 열려 있는 채팅에 대해서만 존재합니다.

• 백필 없음. 폴러는 워크스페이스를 처음 발견할 때 과거 메시지를 건너뜁니다(그렇지 않으면 저널이 넘쳐날 수 있음). 향후 메시지만 캡처됩니다.

• Cursor가 열려 있어야 함. 새로운 메시지가 SQLite에 기록되려면 Cursor가 열려 있어야 합니다. Cursor가 닫혀 있으면 폴러는 정상적으로 실행되지만 새 항목을 기록하지 않습니다.

프로젝트 레이아웃

cursor-chats-bridge/
├── SKILL.md               # YAML frontmatter + Claude-facing instructions
├── README.md              # this file
├── scripts/
│   ├── server.py          # MCP server (Python, ~300 lines)
│   ├── poller.py          # Background poller (Python, ~180 lines)
│   ├── install.ps1        # Idempotent installer
│   └── uninstall.ps1      # Clean removal
└── references/
    └── architecture.md    # Deep technical doc (SQLite layout, edge cases)

기여

풀 리퀘스트를 환영합니다. 특히 다음 사항에 대해 환영합니다:

• macOS / Linux 지원 (cron + Library/Application Support 경로)

• 스키마 복원력: Cursor 버전 변경을 조기에 감지하는 도우미

• 선택적 저널 로테이션 / 압축

• 프랑스어가 아닌 쿼리에서 스킬 트리거 개선

라이선스

MIT — 보증 없이 원하는 대로 사용하세요. LICENSE를 참조하세요.

면책 조항

이 도구는 제3자 도구이며 Anthropic 또는 Cursor와 관련이 없습니다. 비공식적인 수단을 통해 Cursor의 로컬 데이터를 읽으며 향후 Cursor 버전에서 작동하지 않을 수 있습니다. 특히 민감한 데이터를 다루는 컴퓨터에서는 자신의 판단에 따라 사용하십시오.