amazing-marvin-complete-mcp

Amazing Marvin용 MCP(Model Context Protocol) 서버로, 공개 API를 완전히 지원합니다: 약 31개의 문서화된 엔드포인트 전반에 걸친 34개 도구, Marvin의 문서화된 한도를 준수하는 전역 속도 제한기, 최소 권한 토큰 라우팅, MCP 도구 어노테이션을 제공합니다. 도구 설명에 있는 모든 비자명한 동작 주장은 실제 API에 대해 검증되었으며, 그 결과는 아래 Marvin API 특이사항 및 발견 사항에 문서화되어 있습니다. 이 서버를 실행하지 않더라도 유용할 수 있습니다.

있는 그대로 제공됩니다. 이 프로젝트는 적극적으로 유지 관리되지 않으며 지원이 제공되지 않습니다. 이슈는 의도적으로 비활성화되어 있습니다. 자유롭게 포크하세요 — MIT 라이선스입니다.

도구 (34개)

의도적으로 포함하지 않은 것: 스마트 목록 / 작업 선택 로직. Marvin 자체의 Spotlight가 선택을 수행합니다. 서버는 어시스턴트에게 손을 제공할 뿐, 의견을 제공하지 않습니다.

모든 도구는 MCP 도구 어노테이션(readOnlyHint, destructiveHint, idempotentHint, openWorldHint)을携带하므로, 유능한 클라이언트는 delete_task와 reset_reward_points를 마땅히 받아야 할 존중으로 대우할 수 있습니다.

Related MCP server: Super-Productivity-MCP

Marvin 토큰 얻기

두 토큰 모두 Amazing Marvin의 설정 → API에 있습니다 (app.amazingmarvin.com/pre?api):

• API 토큰 (MARVIN_API_TOKEN, 필수) — 제한된 접근 권한; 작업 읽기 및 생성에 충분합니다.

• 전체 접근 토큰 (MARVIN_FULL_ACCESS_TOKEN, 선택 사항이지만 권장됨) — 모든 /doc* 기반 도구에 필요합니다: update_task, set_priority, unmark_done, delete_task, 카테고리 생성, 시간 블록, list_habits, 알림, reset_reward_points.

비밀번호처럼 취급하세요. SECURITY.md를 참조하세요.

설치 및 실행

Python 3.12+가 필요합니다.

git clone <this repo> && cd amazing-marvin-complete-mcp
python -m venv .venv && .venv/bin/pip install .

로컬 (stdio) — Claude Desktop, Claude Code, 모든 MCP 클라이언트

기본 전송 방식은 stdio이므로 클라이언트가 서버를 직접 시작합니다:

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "/path/to/.venv/bin/marvin-mcp",
      "env": {
        "MARVIN_API_TOKEN": "…",
        "MARVIN_FULL_ACCESS_TOKEN": "…",
        "MARVIN_TIMEZONE": "Europe/Stockholm"
      }
    }
  }
}

(Claude Code의 경우: claude mcp add amazing-marvin -e MARVIN_API_TOKEN=… -- /path/to/.venv/bin/marvin-mcp.)

원격 (Streamable HTTP)

MCP_TRANSPORT=http PORT=8787 MCP_AUTH_TOKEN_FILE=/path/to/token \
MARVIN_API_TOKEN_FILE=/path/to/api-token .venv/bin/marvin-mcp

MCP 엔드포인트는 /mcp입니다. 내장된 베어러 검사(MCP_AUTH_TOKEN)는 모든 경로를 보호하지만 완전한 인증 솔루션이 아니라 내부 장벽입니다: TLS가 있는 리버스 프록시를 앞에 두고, Claude 사용자 지정 커넥터의 경우 OAuth 2.1을 지원하는 MCP 인증 프록시를 사용하세요. HTTP 모드용 Dockerfile이 포함되어 있습니다(비루트 사용자로 실행되며, 재시작 시 일일 속도 제한 카운터를 유지하려면 /data에 볼륨을 마운트하세요).

구성

모든 설정은 환경 변수를 통해 이루어집니다 — 전체 주석 목록은 .env.example을 참조하세요. 주요 사항: 모든 비밀 값은 *_FILE 변형을 지원합니다(권장됨). MARVIN_TIMEZONE은 Marvin 계정이 있는 시간대와 일치해야 합니다(기본값은 시스템 시간대이며, 대부분의 컨테이너에서는 UTC입니다).

속도 제한

Marvin의 문서화된 한도 — 초당 1회 쓰기, 3초당 1회 읽기, 하루 1440회 호출 — 은 모든 도구와 세션이 공유하는 단일 프로세스 전역 큐에 의해 여유를 두고(1.1초 / 3.1초) 적용됩니다. 일일 카운터는 재시작 후에도 유지되며(STATE_DIR) 구성된 시간대의 자정에 초기화됩니다. get_rate_limit_status는 오늘의 사용량을 표시합니다.

Marvin API 특이사항 및 발견 사항

아래의 모든 내용은 2026-08-19에 실제 API에 대해 검증되었습니다. 이 저장소의 절반은 실행하지 않고도 사용할 수 있는 부분입니다.

습관

• 비원시 GET /habits는 습관 문서를 읽지 않습니다. 첫 기록 시 지연 생성되는 서버 측 추적 레지스트리를 읽습니다 — 한 번도 기록되지 않은 습관은 응답에 완전히 누락되며, 항목에는 제목이 없습니다(habitId + 기록만 있음). 실제 습관 문서를 나열하려면 ?raw=1(전체 접근 토큰)을 사용하세요. GET /habit?id=…는 추적 레코드를 반환합니다 — 기록은 있지만 제목은 없습니다.

• POST /updateHabit는 부동 소수점으로 직렬화된 정수를 거부합니다: "value": 1.0 → 400 Bad request, "value": 1 → 200. 정수는 정수로 보내세요.

작업 및 프로젝트

• POST /markDone은 작업에만 작동합니다 — 프로젝트는 400 "Can only mark Tasks done with this API"를 받습니다.

• /addTask는 Marvin의 빠른 추가 단축키 구문을 서버 측에서 구문 분석합니다: ~15는 15분 timeEstimate가 되고 +YYYY-MM-DD는 day(일정 — 마감일이 아님)를 설정합니다. 둘 다 제목에서 제거됩니다. 그러나 API를 통해 #Category를 절대 사용하지 마세요: 서버는 문자열을 리터럴로 parentId에 저장합니다(첫 하이픈까지 탐욕적으로, 예: #MCP-TEST → parentId: "#MCP" 및 손상된 제목) 어떤 ID도 확인하지 않습니다. 그러면 작업은 모든 카테고리 밖에 그리고 받은 편지함 밖에 존재하게 되어 사실상 보이지 않게 됩니다. (처음 보고: lucasoeth/marvin-mcp; 여기서 독립적으로 재현됨.)

• 반복 작업의 생성된 인스턴스는 결정적 ID(YYYY-MM-DD_<recurringTaskId>)를 가지므로, API를 통해 완료/미완료로 표시해도 중복이 생성될 수 없습니다. 인스턴스는 Marvin 클라이언트에 의해 생성되므로, 오늘의 반복 작업은 앱이 실행될 때까지 /todayItems에서 누락될 수 있습니다.

• /doc/update는 드물게 일시적인 500을 반환할 수 있습니다. 쓰기는 원자적입니다(부분 상태 없음) — 그냥 재시도하세요. 프로젝트 이름 변경, 이동, 레이블 변경 등은 모두 이를 통해 작동합니다.

• /doc/create는 서버 생성 _id를 다시 에코하지 않습니다 — 이후에 문서를 참조해야 하는 경우 직접 제공하세요.

• /doc/delete를 통한 삭제는 영구적입니다. Marvin의 휴지통은 클라이언트 측입니다.

보상 포인트 및 Kudos

• Kudos(XP/레벨, /kudos로 읽음)와 보상 포인트(청구/청구 취소/사용/초기화)는 두 개의 별도 시스템입니다. /kudos에는 nextMultiplier가 없습니다(MarvinAPI 이슈 #5) — /me에 있습니다.

• /markDone은 작업의 보상 포인트를 지급하지 않습니다 (kudos에 대해서는 이슈 #6 참조) — claimRewardPoints는 별도의 호출입니다.

• MANUAL 청구(itemId: "MANUAL")는 취소할 수 없습니다: 서버에 해당 항목이 저장되지 않으므로 /unclaimRewardPoints는 404 "No such entry"를 반환합니다(points 필드 유무와 관계없이), 음수 포인트 청구는 400으로 거부됩니다. Marvin 웹 앱은 MANUAL을 절대 사용하지 않습니다 — API 전용 기능입니다. 유일한 보상 방법은 같은 금액을 사용하는 것인데, 이는 사용 통계를 부풀립니다.

• /spendRewardPoints는 잔액이 음수가 되면 500을 반환합니다.

알림

• Marvin의 작업 알림은 앱만 동기화 상태를 유지하는 두 번의 쓰기입니다: 작업 문서의 알림 필드(taskTime, reminderTime, reminderOffset, snooze, autoSnooze) 및 /reminder/set을 통한 서버 측 항목. 한쪽만 쓰면(API가 편안하게 허용하는 전부) 앱 UI가 작업에 표시하지 않는 항목 또는 서버 측 고아 항목이 생성됩니다. 독립형 알림(유형 M)이 API의 안전한 사용법입니다. (위험은 Recon2026/marvin-mcp에서 처음 문서화됨; 공식 위키의 자체 경고로 확인됨.)

시간 및 계획

• /todayTimeBlocks는 블록↔카테고리 링크를 생략합니다(이슈 #65); 이 서버는 strategySettings.plannerSmartLists 프로필 문서에서 매핑을 복구합니다.

• API를 통한 시간 추적 중지는 작업 자체의 times/duration 필드를 업데이트하지 않습니다. /tracks가 진실의 원천입니다.

• /addEvent를 통해 생성된 캘린더 이벤트는 Marvin 앱이 어딘가에서 실행되는 동안에만(클라이언트 측 캘린더 동기화) 계속 동기화됩니다.

기존 대안과의 차이점

훌륭한 Amazing Marvin MCP 서버가 여러 개 존재합니다. 이 서버는 그것들을 연구한 후 새로 구축되었으며(공유 코드 없음), 목표가 다릅니다 — 선별된 하위 집합이 아닌 공개 API의 완전한 지원:

• bgheneti/Amazing-Marvin-MCP — 기존의 Python 서버; 광범위하지만 완전하지 않은 지원, 전역 속도 제한 없음.

• Recon2026/marvin-mcp — 더 작은 범위(19개 도구), 비정상적으로 신중한 연구; 두 번 쓰기 위험에 대해 알림을 읽기 전용으로 선택했습니다. 이 서버는 대신 명시적 경고와 함께 알림 쓰기를 제공합니다.

• lucasoeth/marvin-mcp — 다른 철학: API 미러가 아닌 소수의 통합 워크플로 도구(brief/capture/…)와 검색 및 완료된 작업을 위한 직접 CouchDB 읽기(공개 API로는 전혀 불가능). 의견 기반 워크플로나 검색을 원하면 그들의 것을 사용하세요. 문서화된 날카로운 모서리와 함께 원시적이고 완전한 API 접근을 원하면 이 서버를 사용하세요.

• LucaDeLeo/amazing-marvin-mcp — 제한된 API 하위 집합.

크레딧 및 출처

이들 중 어떤 것에서도 코드를 복사하지 않았습니다 — 빌드는 새롭습니다 — 그러나 이들이 실질적으로 형태를 만들었습니다:

• amazingmarvin/MarvinAPI (+ wiki) — 이 서버가 기반으로 하는 공식 API 문서, OpenAPI 사양, 데이터 유형 및 이슈 트래커.

• bgheneti/Amazing-Marvin-MCP — 아키텍처 영감, 초기 격차 분석 중 엔드포인트 참조, MIT 라이선스 선례.

• Recon2026/marvin-mcp — 알림 두 번 쓰기 무결성 위험과 반복 작업 인스턴스에 대한 기초 작업, 둘 다 여기서 검증 및 문서화됨.

• lucasoeth/marvin-mcp — #Category 단축키 버그(여기서 재현됨)와 Marvin의 동기화 데이터베이스가 읽기에 사용 가능한 실제 CouchDB라는 통찰력.

• LucaDeLeo/amazing-marvin-mcp — /addTask가 서버 측에서 단축키 구문을 구문 분석한다는 지적(부분적으로 확인, 부분적으로 반박 — #Category 발견 사항 참조) 및 MCP 도구 어노테이션 아이디어.

Claude Code(Claude Fable 5)로 구축됨.

라이선스

MIT.