JMAP MCP 서버

JMAP(JSON Meta Application Protocol) 이메일 서버와 상호작용하기 위한 도구를 제공하는 MCP(Model Context Protocol) 서버입니다. Deno로 구축되었으며 @htunnicliff/jmap-jam 클라이언트 라이브러리를 사용합니다.

기능

이메일 관리 도구

• 이메일 검색: 텍스트 쿼리, 발신자/수신자 필터, 날짜 범위 및 키워드로 이메일을 검색합니다. 모든 필터는 AND 조건으로 결합됩니다.

• 이메일 가져오기: 구성 가능한 속성 선택을 통해 ID별로 특정 이메일을 검색합니다.

• 스레드 가져오기: 이메일 스레드(대화 체인)를 검색합니다.

• 이메일 표시: 이메일을 읽음/읽지 않음, 플래그 설정/해제로 표시합니다.

• 이메일 이동: 메일함 간에 이메일을 이동합니다.

• 이메일 삭제: 이메일을 영구적으로 삭제합니다.

메일함 관리

• 메일함 가져오기: 계층 구조를 지원하는 모든 메일함/폴더를 나열합니다. 다른 도구에서 필요한 메일함 ID를 찾을 때 사용하세요.

증분 동기화

• 이메일 변경 사항 가져오기: 이전 상태 이후 생성, 업데이트 또는 삭제된 이메일의 ID를 가져옵니다(상태 기반 델타 추적).

• 검색 업데이트 가져오기: 마지막 queryState 이후 이전 검색 쿼리 내의 추가/제거 항목을 가져옵니다.

이메일 작성

• 이메일 보내기: 일반 텍스트 및 HTML을 지원하는 새 이메일을 작성하고 보냅니다.

• 이메일 답장: 자동 헤더 처리 및 전체 답장 지원을 통해 기존 이메일에 답장합니다.

주요 기능

• jmap-jam을 통한 완전한 JMAP RFC 8620/8621 준수

• Zod 스키마를 사용한 포괄적인 입력 유효성 검사

• 모든 목록 작업에 대한 페이지네이션 지원

• 효율적인 폴링을 위한 상태 기반 증분 동기화

• 풍부한 오류 처리 및 연결 관리

• 기능 기반 도구 등록(읽기 전용, 제출)

• 강력한 타이핑을 지원하는 TypeScript 지원

Related MCP server: bare-mcp

설치

Claude Code 플러그인(권장)

플러그인 마켓플레이스를 통해 설치하세요:

/plugin marketplace add wyattjoh/claude-code-marketplace
/plugin install jmap-mcp@wyattjoh-marketplace

그런 다음 MCP 서버 설정에서 필요한 환경 변수를 구성하세요.

사전 요구 사항

• Deno v1.40 이상

• JMAP 호환 이메일 서버(예: Cyrus IMAP, Stalwart Mail Server, FastMail)

• 유효한 JMAP 인증 자격 증명

설정

사용 중인 에이전트에 다음을 추가하세요:

{
  "mcpServers": {
    "jmap": {
      "type": "stdio",
      "command": "deno",
      "args": [
        "run",
        "--allow-net=api.fastmail.com",
        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
        "jsr:@wyattjoh/jmap-mcp@0.6.3"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

FastMail을 사용하지 않는 경우 --allow-net의 api.fastmail.com을 JMAP 서버의 호스트 이름으로 바꾸세요.

사용법

환경 변수

사용 가능한 도구

get_mailboxes

ID, 이름 및 메타데이터와 함께 메일함/폴더를 나열합니다. search_emails(inMailbox) 및 move_emails(mailboxId)에 필요한 메일함 ID를 얻으려면 이 도구를 먼저 호출하세요. 일반적인 이름: Inbox, Drafts, Sent, Trash, Archive, Spam/Junk.

매개변수:

• parentId (선택 사항): 상위 메일함 ID별 필터링

• limit (선택 사항): 최대 결과 수 (1-200, 기본값: 100)

• position (선택 사항): 페이지네이션을 위한 시작 위치

search_emails

필터를 사용하여 이메일을 검색합니다. 모든 필터는 AND 조건으로 결합됩니다. 이메일 ID만 반환하므로 내용을 가져오려면 get_emails를 사용하세요. 결과에는 get_search_updates를 통한 증분 동기화를 위한 queryState가 포함됩니다.

매개변수:

• query (선택 사항): 모든 필드에 걸친 텍스트 검색

• body (선택 사항): 메시지 본문에서만 검색

• from (선택 사항): 발신자 이메일 주소별 필터링

• to (선택 사항): 수신자 이메일 주소별 필터링

• subject (선택 사항): 제목 텍스트별 필터링

• inMailbox (선택 사항): 검색할 메일함 ID (get_mailboxes에서 가져옴)

• hasKeyword (선택 사항): 키워드별 필터링 (예: $seen, $flagged)

• notKeyword (선택 사항): 키워드별 제외 (예: $seen, $draft)

• allInThreadHaveKeyword (선택 사항): 스레드의 모든 이메일에 키워드가 있어야 함

• someInThreadHaveKeyword (선택 사항): 스레드의 최소 하나 이상의 이메일에 키워드가 있어야 함

• before (선택 사항): 날짜 이전의 이메일만 (ISO 8601 날짜/시간)

• after (선택 사항): 날짜 이후의 이메일만 (ISO 8601 날짜/시간)

• limit (선택 사항): 최대 결과 수 (1-100, 기본값: 50)

• position (선택 사항): 페이지네이션을 위한 시작 위치 (기본값: 0)

get_emails

ID별로 특정 이메일을 검색합니다. 필요한 속성만 요청하려면 properties를 사용하세요. 모든 속성을 가져오면 페이로드가 커집니다.

매개변수:

• ids: 이메일 ID 배열 (1-50개 ID)

• properties (선택 사항): 반환할 특정 속성. 권장 세트:

  • 요약: ["id", "subject", "from", "to", "receivedAt", "preview"]

  • 전체 읽기: ["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"]

  • 참고: 본문 내용을 가져오려면 bodyValues와 textBody/htmlBody를 모두 포함하세요.

get_threads

ID별로 이메일 스레드를 가져옵니다. 스레드 ID는 get_emails 응답(threadId 속성)에서 나옵니다. 스레드당 이메일 ID를 반환하므로 내용을 가져오려면 해당 ID로 get_emails를 사용하세요.

매개변수:

• ids: 스레드 ID 배열 (1-20개 ID)

get_email_changes

이전 상태 이후 생성, 업데이트 또는 삭제된 이메일의 ID를 가져옵니다. get_emails 응답의 state 문자열을 사용하세요.

매개변수:

• sinceState: 이전 get_emails 응답의 상태 문자열

• maxChanges (선택 사항): 반환할 최대 변경 사항 (1-500)

• fetchEmails (선택 사항): 변경된 ID에 대한 전체 이메일 세부 정보를 자동으로 가져오기 (기본값: false)

• properties (선택 사항): fetchEmails가 true일 때 가져올 속성

get_search_updates

queryState 이후 이전 검색 쿼리 내의 변경 사항을 가져옵니다. 원래 search_emails 호출과 동일한 필터 매개변수를 사용해야 합니다.

매개변수:

• sinceQueryState: 이전 search_emails 응답의 queryState

• search_emails의 모든 필터 매개변수 (원래 쿼리와 일치해야 함)

• maxChanges (선택 사항): 반환할 최대 변경 사항 (1-500)

mark_emails

이메일을 읽음/읽지 않음 또는 플래그 설정/해제로 표시합니다.

매개변수:

• ids: 이메일 ID 배열 (1-100개 ID)

• seen (선택 사항): 읽음(true) 또는 읽지 않음(false)으로 표시

• flagged (선택 사항): 플래그 설정(true) 또는 해제(false)로 표시

move_emails

이메일을 다른 메일함으로 이동합니다. 대상 메일함 ID를 찾으려면 get_mailboxes를 사용하세요.

매개변수:

• ids: 이메일 ID 배열 (1-100개 ID)

• mailboxId: 대상 메일함 ID (get_mailboxes에서 가져옴)

delete_emails

이메일을 영구적으로 삭제합니다(취소 불가). 복구 가능한 삭제를 원하면 move_emails를 통해 휴지통으로 이동하는 것을 권장합니다.

매개변수:

• ids: 이메일 ID 배열 (1-100개 ID)

send_email

새 이메일을 보냅니다. textBody 또는 htmlBody(또는 둘 다)가 필요합니다.

매개변수:

• to: 수신자 배열 (name 선택 사항, email 필수)

• cc (선택 사항): 참조 수신자 배열

• bcc (선택 사항): 숨은 참조 수신자 배열

• subject: 이메일 제목

• textBody (선택 사항): 일반 텍스트 본문

• htmlBody (선택 사항): HTML 본문

• identityId (선택 사항): 보낼 JMAP ID (생략 시 서버 기본값 사용)

reply_to_email

기존 이메일에 답장합니다. 받는 사람/참조, Re: 제목 접두사 및 스레딩 헤더(In-Reply-To, References)를 자동으로 설정합니다.

매개변수:

• emailId: 답장할 이메일의 ID

• replyAll (선택 사항): 모든 원래 수신자 포함 (기본값: false)

• subject (선택 사항): 사용자 지정 답장 제목 (기본값: Re: <original>)

• textBody (선택 사항): 일반 텍스트 본문

• htmlBody (선택 사항): HTML 본문

• identityId (선택 사항): 보낼 JMAP ID (생략 시 서버 기본값 사용)

JMAP 서버 호환성

이 서버는 다음을 포함하여 모든 JMAP 호환 이메일 서버에서 작동해야 합니다:

• Cyrus IMAP 3.0+

• Stalwart Mail Server

• FastMail (상용)

• Apache James (JMAP 지원 포함)

개발

개발 환경에서 실행

just watch          # Run with file watching
just start          # Run without watching

테스트

just test           # Run all tests
just check          # Format check + lint + type check
just fmt            # Auto-format code

아키텍처

이 서버는 다음을 사용하여 구축되었습니다:

• Deno: 최신 JavaScript/TypeScript 런타임

• @modelcontextprotocol/sdk: MCP 서버 프레임워크

• jmap-jam: 가볍고 타입이 지정된 JMAP 클라이언트

• Zod: 런타임 타입 유효성 검사

보안

• 모든 입력은 Zod 스키마를 사용하여 검증됩니다.

• 민감한 구성에는 환경 변수가 사용됩니다.

• 비밀 정보는 로그에 기록되거나 응답에 노출되지 않습니다.

• JMAP 보안 모범 사례를 따릅니다.

기여

1. 저장소를 포크합니다.

2. 기능 브랜치를 만듭니다.

3. 함수형 프로그래밍 스타일을 따라 변경 사항을 적용합니다.

4. 변경 사항을 철저히 테스트합니다.

5. 풀 리퀘스트를 제출합니다.

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

관련 프로젝트

• jmap-jam - JMAP 클라이언트 라이브러리

• Model Context Protocol - MCP 사양

• JMAP RFC 8620 - JMAP 핵심 프로토콜

• JMAP RFC 8621 - 메일을 위한 JMAP