amazing-marvin-mcp

개요

Amazing Marvin용 비공식 MCP 서버입니다. Claude와 같은 어시스턴트가 "내 받은 편지함에 뭐가 있지?", "이번 주에 마감인 게 뭐지?", "차에 있는데 뭘 할 수 있지?" 같은 질문에 답하고, 이름 변경, 라벨 변경, 일정 변경, 이동, 프로젝트로 분할, 연구 내용을 메모로 저장하는 등의 작업을 실행할 수 있게 해줍니다.

이 프로젝트는 Amazing Marvin과 제휴, 보증, 지원 관계가 없으며, 그들의 공개 API를 사용합니다.

작동 방식

Claude ──MCP (stdio)──▶ amazing-marvin-mcp
                          ├─ local mirror ◀── CouchDB `_changes` (your sync database)
                          │    reads, search and filters run here: no rate-limit cost
                          └─ writes ──▶ Marvin REST API (addTask, doc/update, markDone)
                                        throttled to Marvin's limits (1 request / 3 s)

Marvin의 REST API에는 "목록" 또는 "검색" 엔드포인트가 없고 하루 1440회 요청 한도가 있으므로, 읽기는 증분 _changes 폴링(최소 1분 간격)으로 최신 상태를 유지하는 로컬 데이터베이스 사본에서 수행됩니다. 쓰기는 REST API를 통해 이루어지며, Marvin의 충돌 해결 장부(fieldUpdates)는 서버 측에서 처리됩니다.

어시스턴트가 아는 것

• Marvin 의미론 — UI 자체의 표현을 사용합니다. 받은 편지함 = 어디에도 분류되지 않음; 카테고리와 프로젝트는 임의로 중첩됩니다(마스터 목록). 네 가지 날짜는 구분됩니다: 실행 날짜(실행할 계획이 있는 날, "예정"), 마감 날짜(하드 외부 데드라인), 종료 날짜(자체 설정 목표; Planning Ahead의 계획 주/월은 더 유연한 형태), 시작 날짜(그때까지 Backburner에 숨김). 또한 기간 추정(분), 중요도(P1–P3 별), Eat-the-Frog, Backburner, 라벨 및 라벨 그룹이 포함됩니다.

• 사용자의 구조(get_structure): ID와 미완료 작업 수가 포함된 카테고리/프로젝트 트리, 그룹별 라벨, 그리고 활성화한 Marvin 전략(Strategies 화면의 이름 기준).

• 사용자의 워크플로(workflow.md 또는 workflow/ 섹션 디렉터리): 사용자가 Marvin을 어떻게 사용하는지 — 라벨의 의미, 계획 방법, 받은 편지함 분류 체크리스트, "단기 승리"의 의미. Marvin은 유연하므로, 이것이 어시스턴트가 사용자처럼 행동하게 만드는 핵심입니다. 서버 지침에 주입되며 marvin://workflow(및 marvin://workflow/<section>)로 노출됩니다.

도구

의도적으로 삭제 도구는 없습니다. Marvin의 휴지통은 클라이언트 측이므로 API 삭제는 복구할 수 없습니다.

Related MCP server: Amazing Marvin MCP

설치 및 설정 (사용하기)

1. 설치 (uv 필요):

   uv tool install git+https://github.com/tsvikas/amazing-marvin-mcp.git

2. 자격 증명. Marvin에서 API 전략을 활성화합니다(Strategies → API → 설정). 해당 값을 ~/.config/amazing-marvin-mcp/.env에 넣습니다(Linux 기준; amazing-marvin-mcp check가 사용자 OS의 정확한 경로를 출력합니다):

   MARVIN_API_TOKEN=...           # create / mark done
   MARVIN_FULL_ACCESS_TOKEN=...   # edit existing items; omit for no edits
   MARVIN_SYNC_SERVER=...         # CouchDB: the read mirror
   MARVIN_SYNC_DATABASE=...
   MARVIN_SYNC_USER=...
   MARVIN_SYNC_PASSWORD=...

   환경 변수와 작업 디렉터리의 .env도 작동합니다(사용자별 파일보다 우선). 시험 중에는 두 번째, 임시 Marvin 계정을 사용하세요: 전체 액세스 토큰은 데이터를 손상시킬 수 있습니다.

3. 확인 및 첫 동기화:

   amazing-marvin-mcp check     # verifies tokens, pulls the database, prints counts

4. 워크플로 설명:

   amazing-marvin-mcp init-workflow            # one workflow.md to edit, or
   amazing-marvin-mcp init-workflow --split    # a workflow/ directory: planning, labels, triage, daily…

   그 안의 모든 내용이 모델의 지침에 포함됩니다(각 섹션은 marvin://workflow/<section> 리소스이기도 함). 짧고 구체적으로 유지하세요.

5. MCP 클라이언트에 등록.

   Claude Code:

   claude mcp add marvin -- amazing-marvin-mcp serve

   Claude Desktop(claude_desktop_config.json):

   {
     "mcpServers": {
       "marvin": { "command": "amazing-marvin-mcp", "args": ["serve"] }
     }
   }

   둘 다 사용자별 .env를 읽으므로 클라이언트 구성에 비밀이 포함되지 않습니다. 그런 다음 "내 Marvin 받은 편지함에 뭐가 있지?"라고 물어보세요.

기타 설정(check로 표시): MARVIN_WORKFLOW_FILE(파일 또는 디렉터리), MARVIN_CACHE_DIR, MARVIN_MIN_REQUEST_INTERVAL(REST 호출 사이의 초, 기본값 3), MARVIN_MIRROR_MAX_AGE(읽기가 다시 폴링하기 전의 초, 기본값 60).

미러 파일은 모든 작업을 보유하며, 캐시 디렉터리 아래에 소유자 전용 권한으로 작성됩니다.

개발

git clone https://github.com/tsvikas/amazing-marvin-mcp && cd amazing-marvin-mcp
uv sync && just prepare                     # deps + pre-commit hooks
just test && just lint

체크아웃에서 서버를 실행합니다(저장소 루트의 .env는 git-ignored이며 클라이언트가 이 디렉터리에서 시작할 때 인식됩니다. 그렇지 않으면 -e VAR=value 또는 사용자별 파일을 사용하세요):

claude mcp add marvin-dev -- uv run --directory "$PWD" amazing-marvin-mcp serve

tests/test_live.py는 모든 도구를 종단 간 실행하며 기본적으로 기록된 캐세트(tests/cassettes/)를 재생합니다. 이는 실제 Marvin 문서의 픽스처 역할도 합니다. 임시 계정으로 다시 기록하려면(몇 개의 [live] 항목을 생성한 후 삭제합니다):

MARVIN_API_TOKEN=... MARVIN_FULL_ACCESS_TOKEN=... MARVIN_SYNC_SERVER=... \
MARVIN_SYNC_DATABASE=... MARVIN_SYNC_USER=... MARVIN_SYNC_PASSWORD=... \
uv run pytest tests/test_live.py --record-mode=rewrite

기여를 위한 설계 규칙은 CLAUDE.md에 있습니다.

기여

기여에 관심이 있으신가요? 개발 설정 및 지침은 CONTRIBUTING.md를 참조하세요.