mal-mcp

MyAnimeList v2 API를 Claude 및 기타 MCP 호환 클라이언트에 노출하는 Model Context Protocol 서버입니다. TypeScript로 작성되었으며 Bun을 통해 stdio로 로컬에서 실행되거나, 호스팅되는 다중 사용자 서버로서 Cloudflare Workers에 배포할 수 있습니다.

도구

설정

• configure — stdio 전용 — 사용자의 MyAnimeList client_id(및 발급된 경우 client_secret)를 저장합니다. 다른 도구를 호출하기 전에 반드시 호출해야 합니다. Worker에는 등록되지 않으며, Worker에서는 사용자가 클라이언트에 서버를 추가할 때 MCP OAuth 흐름을 통해 로그인합니다.

• authenticate — stdio 전용(의미 있음) — MAL OAuth 흐름을 시작합니다. 브라우저를 열고 로컬 콜백을 기다립니다. Worker에서는 호환성을 위해 유지되는 no-op(아무 작업도 하지 않음)이며, 인증은 MCP OAuth를 통해 연결 시 자동으로 수행됩니다.

• get_auth_status — 자격 증명 및 사용자 토큰을 사용할 수 있는지 확인합니다.

공개 (Client ID 전용)

• search_anime — 제목으로 애니메이션 검색

• get_anime_details — 애니메이션 ID에 대한 전체 세부 정보

• get_anime_ranking — 순위 목록 (전체, 방영 중, 예정, TV, OVA, 영화, 스페셜, 인기순, 즐겨찾기순)

• get_seasonal_anime — 연도 + 시즌별 애니메이션

• search_manga — 제목으로 만화 검색

• get_manga_details — 만화 ID에 대한 전체 세부 정보

• get_manga_ranking — 순위 목록 (전체, 만화, 소설, 단편, 동인지, 만화(manhwa), 만화(manhua), 인기순, 즐겨찾기순)

사용자 범위 (OAuth2 액세스 토큰 필요)

• get_current_user — 인증된 사용자의 프로필 + 애니메이션 통계

• get_anime_suggestions — 개인화된 애니메이션 추천

• get_user_anime_list — 모든 사용자의 공개 애니메이션 목록 읽기 (또는 @me)

• update_anime_list_status — 목록 상태, 점수, 시청한 에피소드 등을 추가/업데이트

• delete_anime_list_item — 목록에서 애니메이션 삭제

• get_user_manga_list — 모든 사용자의 공개 만화 목록 읽기 (또는 @me)

• update_manga_list_status — 목록 상태, 점수, 읽은 챕터 등을 추가/업데이트

• delete_manga_list_item — 목록에서 만화 삭제

Related MCP server: Claude Code MCP

옵션 1: stdio를 통해 로컬에서 실행

1. 설치

bun install

2. MCP 클라이언트에 연결

claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json)에 추가합니다:

{
  "mcpServers": {
    "mal": {
      "command": "bun",
      "args": ["C:\\BrunoLM\\Projects\\mal-mcp\\src\\index.ts"]
    }
  }
}

Claude Code의 경우 claude mcp add를 사용하거나 해당 블록을 .claude/mcp.json에 넣으십시오.

3. MAL 자격 증명 구성

https://myanimelist.net/apiconfig에서 API 클라이언트를 생성합니다:

• App Type: other / web

• App Redirect URL: http://localhost:8765/callback

그런 다음 MCP 클라이언트에서 client_id(및 MAL에서 발급한 경우 client_secret)와 함께 configure 도구를 호출합니다. 자격 증명은 ~/.mal-mcp-config.json에 저장됩니다.

4. (선택 사항) 사용자 범위 도구에 대한 권한 부여

MCP 클라이언트에서 authenticate를 호출합니다. 브라우저가 열리고 요청을 승인하면 포트 8765의 로컬 서버가 리디렉션을 포착하여 토큰이 ~/.mal-mcp-tokens.json에 저장됩니다. 서버는 거기서 자동으로 토큰을 갱신합니다.

CLI를 선호하는 경우:

$env:MAL_CLIENT_ID = "your-client-id"
# $env:MAL_CLIENT_SECRET = "your-client-secret"   # only if issued
bun run auth

옵션 2: Cloudflare Workers에서 호스팅 (다중 사용자, MCP OAuth)

단일 Worker가 표준 MCP OAuth 2.1(동적 클라이언트 등록)을 통해 모든 사용자에게 서비스를 제공합니다. 모두를 위한 단일 URL: https://mal-mcp.<account>.workers.dev/mcp. 로그인하는 동안 각 사용자는 자신의 MAL client_id(및 발급된 경우 client_secret)를 제공하며, 사용자별 상태는 해당 자격 증명의 해시로 키가 지정된 Durable Object에 저장됩니다.

1. 운영자 설정 (1회)

bun install
bunx wrangler login
bunx wrangler kv namespace create OAUTH_KV

반환된 네임스페이스 id를 wrangler.jsonc에 붙여넣고(REPLACE_WITH_KV_ID를 대체) 배포합니다:

bun run worker:deploy

로컬 개발의 경우:

bunx wrangler kv namespace create OAUTH_KV --preview
bun run worker:dev

2. 각 사용자 연결

1. https://myanimelist.net/apiconfig에서 MAL API 클라이언트를 생성합니다(App Type: other). App Redirect URL을 다음으로 설정합니다:

   https://mal-mcp.<account>.workers.dev/mal/callback

   (이 정확한 URL — 특정 배포의 모든 사용자에게 동일합니다.)

2. MCP 클라이언트에 MCP 서버를 추가합니다:

   claude mcp add --transport http mal https://mal-mcp.<account>.workers.dev/mcp

   또는 구성에서 동일하게 설정:

   {
     "mcpServers": {
       "mal": {
         "url": "https://mal-mcp.<account>.workers.dev/mcp"
       }
     }
   }

3. 처음 연결 시 MCP 클라이언트가 브라우저 탭을 띄웁니다. Worker의 승인 페이지에서 MAL client_id(및 발급된 경우 client_secret)를 요청하고, MyAnimeList로 리디렉션하여 승인하게 한 다음, MCP 클라이언트로 돌아오면 로그인이 완료됩니다. 액세스 및 갱신 토큰은 Durable Object에 저장되며, MAL 액세스 토큰은 자동으로 갱신됩니다.

호스팅 배포를 위한 보안 참고 사항

• Worker는 MCP를 위한 자체 OAuth 2.1 인증 서버입니다. MCP 클라이언트에 발급된 Bearer 토큰은 사용자에게 범위가 지정됩니다. 토큰이 유출되면 토큰이 만료될 때까지 소지자가 사용자를 대신하여 MAL을 호출할 수 있습니다.

• 서로 다른 MAL 자격 증명 → 서로 다른 Durable Object → 완전히 분리된 상태. 사용자 간 공유 상태는 없습니다.

• Worker는 자체적인 MAL 자격 증명을 보유하지 않으며, 각 사용자가 자신의 MAL API 클라이언트를 제공합니다.

데이터 저장

stdio

홈 디렉토리에 있는 두 개의 일반 텍스트 JSON 파일이며, 모드 0600(소유자 읽기/쓰기 전용)으로 생성됩니다:

해당 상태를 재설정하려면 파일을 삭제하십시오. myanimelist.net 및 api.myanimelist.net 외에는 어디로도 데이터가 전송되지 않습니다.

호스팅된 Worker

두 개의 Cloudflare 저장소 표면:

OAUTH_KV (Workers KV 네임스페이스) — @cloudflare/workers-oauth-provider 및 MAL 승인 릴레이에서 사용:

• 등록된 OAuth 클라이언트(동적 클라이언트 등록), 인증 권한 부여 및 액세스/갱신 토큰. 제공자는 권한 부여 props를 암호화하여 저장하며, 암호화 키는 발급된 토큰 자체에 래핑되므로 KV 스냅샷만으로는 props를 복구할 수 없습니다.

• 임의의 상태 문자열로 키가 지정된 단기(10분 TTL) 보류 중인 MAL 인증 레코드. 각 레코드는 보류 중인 승인 URL, 사용자의 MAL client_id/client_secret, PKCE 검증기 및 콜백 URL을 보유합니다. 항목은 MAL 콜백이 소비하는 즉시 삭제되거나 그렇지 않으면 자동으로 만료됩니다. 이들은 KV에 일반 텍스트 JSON으로 저장됩니다.

MAL_SESSION (Durable Object, 사용자당 하나) — u:<32-hex>로 키가 지정되며, 여기서 hex는 sha256("v1:" + mal_client_id + ":" + (mal_client_secret ?? ""))의 처음 32자입니다. DO의 SQLite 저장소에 일반 텍스트로 저장됩니다(Cloudflare는 디스크의 DO 저장소를 암호화함):

• config: 사용자의 MAL client_id 및 (발급된 경우) client_secret.

• tokens: MAL access_token, refresh_token, expires_at.

두 개의 서로 다른 MAL 자격 증명 쌍은 두 개의 서로 다른 해시를 생성하며 → 공유 상태가 없는 완전히 분리된 두 개의 Durable Object가 생성됩니다.

저장되지 않는 것: 애니메이션/만화 목록, 사용자 프로필 데이터, 검색 결과 또는 MAL에서 반환된 기타 모든 데이터 — 이러한 데이터는 요청 시 요청을 통해 직접 흐릅니다. 분석 데이터나 표준 Cloudflare 관찰 가능성 지표를 넘어서는 요청 내용에 대한 로그는 없습니다.

네트워크를 통해 이동하는 것: MAL client_id/client_secret은 HTTPS를 통해 브라우저에서 승인 페이지로 양식 필드로 제출됩니다. MAL 액세스 토큰은 Authorization: Bearer …로 api.myanimelist.net에 전달됩니다.

사용자 상태 재설정: MCP 클라이언트에서 권한을 취소하거나(또는 다시 연결), 운영자에게 연락하여 일치하는 Durable Object를 삭제하십시오. 동일한 MAL 자격 증명으로 다시 인증하면 동일한 DO와 기존 토큰이 재사용됩니다.

환경 변수 (stdio 전용)

호스팅된 Worker 배포에서는 이러한 환경 변수가 사용되지 않으며, 각 최종 사용자는 MCP OAuth 로그인 중에 Worker의 승인 페이지를 통해 자신의 MAL 자격 증명을 제공합니다.

개발

bun run dev              # stdio, watch mode
bun run worker:dev       # Worker, local (miniflare)
bun run typecheck        # tsc --noEmit

모든 도구는 MAL로 직접 전달되는 선택적 fields 문자열을 사용합니다. 기본값을 재정의해야 하는 경우 필드 사양을 참조하십시오.