mal-mcp

Сервер Model Context Protocol, предоставляющий доступ к MyAnimeList v2 API для Claude и других MCP-совместимых клиентов. Написан на TypeScript, запускается локально через Bun по stdio или развертывается в Cloudflare Workers как хостинговый многопользовательский сервер.

Инструменты

Настройка

• configure — только stdio — сохранение client_id (и client_secret, если он был выдан) пользователя MyAnimeList. Должен быть вызван перед любым другим инструментом. Не регистрируется в 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 — рейтинговые списки (все, транслируемые, предстоящие, ТВ, 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

Создайте API-клиент на странице https://myanimelist.net/apiconfig:

• App Type: other / web

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

Затем из вашего MCP-клиента вызовите инструмент configure с вашим client_id (и client_secret, если MAL его выдал). Учетные данные сохраняются в ~/.mal-mcp-config.json.

4. (Опционально) Авторизация для пользовательских инструментов

Вызовите authenticate из вашего MCP-клиента. Откроется браузер, вы подтвердите запрос, локальный сервер на порту 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 (Dynamic Client Registration). Один URL для всех: https://mal-mcp.<account>.workers.dev/mcp. При входе каждый пользователь предоставляет свой собственный client_id MAL (и 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. Создайте API-клиент MAL на https://myanimelist.net/apiconfig (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 запросит ваш client_id MAL (и client_secret, если выдан), перенаправит вас на MyAnimeList для подтверждения, а затем вернет в ваш MCP-клиент — теперь вы вошли в систему. Токены доступа и обновления сохраняются в вашем Durable Object; токен доступа MAL обновляется автоматически.

Заметки по безопасности для хостинговых развертываний

• Worker является собственным сервером авторизации OAuth 2.1 для MCP. Токены Bearer, выданные вашему MCP-клиенту, привязаны к вам; утечка токена позволит злоумышленнику вызывать MAL от вашего имени до истечения срока действия токена.

• Разные учетные данные MAL → разные Durable Object → полностью раздельное состояние. Общего состояния между пользователями нет.

• Worker не хранит учетные данные MAL; каждый пользователь предоставляет свой собственный API-клиент MAL.

Хранение данных

stdio

Два текстовых JSON-файла в вашей домашней директории, созданные с правами 0600 (только чтение/запись владельцем):

Удалите любой из файлов, чтобы сбросить соответствующее состояние. Никакие данные не отправляются никуда, кроме myanimelist.net и api.myanimelist.net.

Хостинговый Worker

Две поверхности хранения Cloudflare:

OAUTH_KV (пространство имен Workers KV) — используется @cloudflare/workers-oauth-provider и реле авторизации MAL:

• Зарегистрированные OAuth-клиенты (Dynamic Client Registration), разрешения на авторизацию и токены доступа/обновления. Провайдер хранит props разрешений в зашифрованном виде; ключ шифрования встроен в сам выданный токен, поэтому одних снимков KV недостаточно для восстановления props.

• Кратковременные (TTL 10 минут) записи ожидающей авторизации MAL, ключом которых является случайная строка состояния. Каждая запись содержит ожидающий URL авторизации, ваш client_id/client_secret MAL, верификатор PKCE и URL обратного вызова. Записи удаляются, как только обратный вызов MAL их использует, или истекают автоматически. Они хранятся как обычный JSON в KV.

MAL_SESSION (Durable Object, один на пользователя) — ключ u:<32-hex>, где hex — первые 32 символа sha256("v1:" + mal_client_id + ":" + (mal_client_secret ?? "")). Хранится в виде обычного текста в хранилище SQLite объекта DO (Cloudflare шифрует хранилище DO на диске в состоянии покоя):

• config: ваш client_id MAL и (если выдан) client_secret.

• tokens: access_token, refresh_token, expires_at MAL.

Две разные пары учетных данных MAL создают два разных хеша → два полностью раздельных Durable Object без общего состояния.

Что не хранится: списки аниме/манги, данные профиля пользователя, результаты поиска или что-либо еще, возвращаемое из MAL — эти данные проходят через запрос по требованию. Никакой аналитики, никаких логов содержимого запросов, кроме стандартных метрик наблюдаемости Cloudflare.

Что передается по сети: client_id/client_secret MAL отправляются как поля формы из вашего браузера на страницу авторизации по HTTPS. Токены доступа MAL пересылаются как Authorization: Bearer … на api.myanimelist.net.

Сброс состояния пользователя: отзовите разрешение в вашем MCP-клиенте (или переподключитесь), либо свяжитесь с оператором для удаления соответствующего Durable Object. Повторная авторизация с теми же учетными данными MAL повторно использует тот же DO и его существующие токены.

Переменные окружения (только stdio)

В хостинговых развертываниях Worker эти переменные окружения не используются; каждый конечный пользователь предоставляет свои учетные данные MAL через страницу авторизации Worker во время входа через MCP OAuth.

Разработка

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

Все инструменты принимают необязательную строку fields, которая передается напрямую в MAL — см. спецификацию полей, если вам нужно переопределить значения по умолчанию.