spacemail-mcp

Claude가 하나 이상의 Spacemail(Spaceship 비즈니스 이메일) 사서함에 접근할 수 있게 해주는 MCP 서버입니다.

이런 방식으로 동작하는 이유

docs.spaceship.dev에 있는 Spaceship 공개 API는 도메인, DNS, SellerHub를 다룹니다. 메일함 엔드포인트가 없기 때문에 메일에 대해 감쌀 것이 없습니다. Spacemail은 표준 IMAP과 SMTP를 노출하며 기본적으로 활성화되어 있으므로 이 서버는 해당 프로토콜에 직접 연결합니다:

사용자 이름은 전체 Spacemail 주소이고, 비밀번호는 해당 사서의 자체 비밀번호입니다.

Related MCP server: IMAP MCP Server

도구

모든 도구는 선택적 account 인수를 사용합니다. 사서함이 하나만 구성되어 있으면 해당 인수는 무시됩니다. 여러 개가 있다면 생략 시 기본값을 사용합니다. search_messages는 account: "*"도 허용하여 한 번에 모든 사서함을 검색할 수 있습니다.

의도적으로 두 가지는 제외했습니다.

• 영구 삭제는 없습니다. 어떤 도구가 할 수 있는 최악의 동작은 메시지를 휴지통으로 이동하는 것이며, 다시 이동하면 되돌릴 수 있습니다.

• 발송은 계정별 선택 사항입니다. send_message는 특정 사서함에 대해 allowSend가 true인 경우에만 동작하며, 그렇지 않으면 요청을 거부합니다. 이 설정을 끈 상태에서 save_draft를 사용하면 인간이 실제로 보내기 버튼을 누르게 됩니다.

설정

1. 설치

Node.js 18 이상이 필요합니다.

cd path/to/spacemail-mcp
npm install

2. accounts.json 만들기

accounts.example.json을 accounts.json으로 복사한 다음 채워 넣으세요. 이 파일은 gitignore 대상입니다.

{
  "accounts": [
    {
      "label": "personal",
      "user": "you@example.com",
      "password": "the-mailbox-password",
      "default": true,
      "fromName": "Your Name"
    },
    {
      "label": "work",
      "user": "hello@example.org",
      "password": "the-other-password"
    }
  ]
}

계정별 필드: label(대화에서 부르는 이름), user, password, 그리고 선택적으로 default, fromName, allowSend, imapHost, imapPort, smtpHost, smtpPort.

라벨은 고유해야 합니다. label을 생략하면 주소에서 파생되므로, 서로 다른 도메인에 있고 동일한 로컬 부분(info@a.com과 info@b.com)을 가진 두 사서함은 모두 info가 되어 서버가 시작을 거부합니다. 명시적인 라벨을 지정하세요.

비밀번호는 Spacemail Manager에서 얻습니다: 구독을 찾아 사서함 옆의 점 3개(⋯)를 클릭하고 IMAP/POP3/SMTP를 선택하세요. 비밀번호가 더 없다면 해당 화면에서 재설정할 수 있습니다.

3. Claude 데스크톱 앱에 등록

설정에서 개발자, 다음에 구성 편집을 선택하면, %APPDATA%\Claude\claude_desktop_config.json이 열립니다:

{
  "mcpServers": {
    "spacemail": {
      "command": "node",
      "args": ["C:\\path\\to\\spacemail-mcp\\index.js"],
      "env": {
        "SPACEMAIL_CONFIG": "C:\\path\\to\\spacemail-mcp\\accounts.json"
      }
    }
  }
}

JSON에서는 백슬래시가 이중으로 백슬래시 처리되어야 합니다. 이후 시스템 트레이에서 앱을 완전히 재시작하세요.

또는 Claude Code CLI를 사용:

claude mcp add --transport stdio spacemail ^
  --env SPACEMAIL_CONFIG="C:\path\to\spacemail-mcp\accounts.json" ^
  -- node "C:\path\to\spacemail-mcp\index.js"

4. 확인

Claude에게 계정 인수 없이 test_connection을 실행하도록 요청하세요. 모든 사저함을 테스트하고 각각을 ok 또는 failed로 독립적으로 보고하므로, 하나의 잘못된 비밀번호가 다른 결과를 가리지 않습니다.

자격 증명을 제공하는 다른 방법

이 순서대로 확인됩니다. 가장 먼저 존재하는 항목이 우선합니다.

1. 구성 파일(둘 이상의 사서함에 권장)

위 JSON 파일을 가리키는 SPACEMAIL_CONFIG입니다.

2. 번호가 붙은 환경 변수

SPACEMAIL_1_USER, SPACEMAIL_1_PASSWORD, SPACEMAIL_1_LABEL, SPACEMAIL_1_DEFAULT, SPACEMAIL_1_ALLOW_SEND, SPACEMAIL_1_FROM_NAME, 그 다음 SPACEMAIL_2_* 등으로 최대 20개까지 사용할 수 있습니다.

3. 단일 계정

SPACEMAIL_USER와 SPACEMAIL_PASSWORD, 그리고 선택적으로 SPACEMAIL_IMAP_HOST, SPACEMAIL_IMAP_PORT, SPACEMAIL_SMTP_HOST, SPACEMAIL_SMTP_PORT, SPACEMAIL_ALLOW_SEND, SPACEMAIL_FROM_NAME을 사용합니다.

문제 해결

서버가 시작되지 않습니다. 읽을 수 없는 구성 파일, 누락된 비밀번호, 중복 라벨, 아니면 사서들이 전혀 구성되지 않은 경우와 메시지를 stdout으로 출력하면서 종료됩니다. 해당 폴더에서 직접 node index.js를 실행해 확인하세요.

한 사서함이 실패하고 다른 사서함은 정상입니다. 인수 없이 test_connection을 실행하세요. 각 계정이 별도로 보고됩니다. 일반적인 원인은 사용자 이름이 전체 이메일 주소가 아니거나 Spacemail Manager에서 해당 사서함의 IMAP이 비활성화되어 있는 것입니다.

Claude에서 저버가 연결되지 않음으로 표시됩니다. MCP 하위 프로세스는 터미널과 다른 환경에서 시작되므로 node가 경로(PATH)에 없을 수 있습니다. where node가 알려주는 node.exe의 전체 절대 경로를 사용하세요.

search_messages가 아무것도 찾지 못합니다. 폴더 경로는 대소문자를 구분하며 다양합니다. 먼저 list_folders를 실행하고 반환된 정확한 path 값을 사용하세요.

보내기가 거부됩니다. allowSend를 특정 계정에 대해 true로 설정해야 합니다. Spacemail에서는 요금제별로 나가는 메일의 용량 제한도 있습니다.