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上では互換性のために残されているノーオペレーション（何もしない）です。認証は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 — ランキングリスト（すべて、マンガ、小説、読み切り、同人、マンファ、マンホア、人気順、お気に入り）

ユーザースコープ（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クライアントから configure ツールを呼び出し、client_id（およびMALが発行した場合は client_secret）を入力します。資格情報は ~/.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. オペレーターのセットアップ（初回のみ）

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クライアントにサーバーを追加します：

   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クライアントに発行されたベアラートークンはユーザーごとにスコープが限定されています。トークンが漏洩した場合、有効期限が切れるまで第三者がユーザーの代わりにMALを呼び出すことが可能です。

• MAL資格情報が異なれば、Durable Objectも異なり、状態は完全に分離されます。ユーザー間で共有される状態はありません。

• Worker自体はMAL資格情報を保持しません。各ユーザーが自身のMAL APIクライアントを提供します。

データストレージ

stdio

ホームディレクトリに作成される2つのプレーンテキストJSONファイル（モード 0600、所有者のみ読み書き可能）：

いずれかのファイルを削除すると、対応する状態がリセットされます。myanimelist.net および api.myanimelist.net 以外には何も送信されません。

ホスト型Worker

2つのCloudflareストレージ領域を使用します：

OAUTH_KV (Workers KV名前空間) — @cloudflare/workers-oauth-provider およびMAL承認リレーによって使用されます：

• 登録済みOAuthクライアント（動的クライアント登録）、認可グラント、アクセストークン/リフレッシュトークン。プロバイダーはグラントの props を暗号化して保存します。暗号化キーは発行されたトークン自体にラップされているため、KVのスナップショットだけでは props を復元できません。

• ランダムな状態文字列をキーとする、短命（TTL 10分）の保留中MAL認証レコード。各レコードには、保留中の承認URL、MAL client_id/client_secret、PKCE検証コード、コールバックURLが保持されます。MALコールバックが消費すると即座に削除されるか、期限切れで自動的に削除されます。これらは KV内にプレーンテキストのJSONとして保存されます。

MAL_SESSION (Durable Object、ユーザーごとに1つ) — 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。

2つの異なるMAL資格情報のペアは2つの異なるハッシュを生成し、共有状態のない完全に分離された2つの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 文字列を受け取ります。デフォルトを上書きする必要がある場合は、フィールド仕様を参照してください。