npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@cyanheads/anime-mcp-server

v0.5.0

Published

Search anime/manga, get full detail, franchise relations, seasonal schedule, characters, rankings, and studio filmography via MCP. STDIO or Streamable HTTP.

Readme

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework


Overview

Anime and manga data from AniList, Jikan (MyAnimeList), and Kitsu. Search titles, pull full detail with side-by-side AniList and MAL scores, walk a franchise's relation graph, check the airing schedule, and look up characters, voice actors, and studio filmographies.

Tools

| Tool | Description | |:---|:---| | anime_search_media | Search anime or manga by title, genre, tag, release year, country, format, or status; anime also supports broadcast seasons. AniList primary; Jikan (MAL) fallback when AniList has no match for a title-only query. | | anime_get_media | Full detail for one anime or manga by AniList ID — synopsis, format, episode/chapter count, status, season, studios, source material, genres and tags (spoiler-flagged), AniList and MAL scores side by side, streaming links, cover/banner, and direct relations. | | anime_get_relations | Walks the related-works graph within a hop limit. Groups main and supplementary entries by relation priority, then year; not a strict chronology. | | anime_get_schedule | Airing schedule for a season or upcoming episode window. Season mode lists all anime airing in a given season/year. Upcoming mode returns the next episode for each airing title within a date window, with UTC timestamp and countdown. | | anime_find_characters | Characters and voice actors for a title, or look up a character/VA by name or exact AniList person ID. Name lookups include other matching people; results link to their media appearances. | | anime_get_recommendations | Page AniList recommendations with matching MAL votes, or Jikan candidates resolved through AniList. Reports the selected source and Jikan availability; optionally echoes what you liked. | | anime_get_rankings | Top, trending, or seasonal rankings. Filterable by genre, tag, and format. Top returns all-time by score; trending uses AniList's trending order; seasonal returns the current or specified season sorted by popularity. | | anime_get_studio | A studio's filmography by name or AniList studio ID, optionally restricted to main-studio credits before pagination. Sort by year, score, or popularity. |

Resources

| Resource | Description | |:---|:---| | anime://media/{id} | Compact media record by AniList ID — title, synopsis, scores, genres, streaming count, and cover image. Stable URI for injectable context. | | skill://anime-guide/SKILL.md | Caller guide for franchise research, cast-to-career lookups, studio filmographies, and recommendation coverage. Also included in plugin, npm, Docker, and MCPB installs. |

Media resource data is also reachable via tools. Use anime_search_media to discover AniList IDs before fetching its resource URI.


Capability reference

anime_search_media tool

  • Search anime or manga by title, genre, tag, start_year, country_of_origin (ISO alpha-2, such as JP or KR), format, status, or up to 5 sort values; at least one criterion is required. season/season_year apply only to anime (anime_only_season otherwise). page/per_page pages results (max 50), and include_adult: true opts into adult titles
  • Results carry AniList IDs, titles, scores, and episode/chapter counts. AniList is primary; title-only searches with no match can fall back to Jikan at per_page 25 or less. Follow has_next_page; AniList total_results is exact on a nonempty final page or zero on an empty first page, and null otherwise. Jikan totals remain null
  • AniList serves only the first 5,000 search, season, and ranking entries; deeper pages fail with page_depth_exceeded, so narrow the criteria instead
  • effectiveQuery echoes normalized criteria on both surfaces. Empty first-page genre searches can suggest the corresponding AniList tag. Year and country filters remain on AniList and suppress the title-only fallback

anime_get_media tool

  • Fetch full detail by AniList id, with adult content requiring include_adult: true; discover IDs through anime_search_media
  • Returns synopsis, genres, spoiler-flagged tags, studios, direct relations, images, separate AniList/MAL scores, release dates at their known precision, episode duration, origin, alternate titles, and supported trailer links. Streaming destinations merge Kitsu and enabled AniList links; Kitsu retains its language detail on duplicate hosts
  • data_sources identifies successful supplements; a notice names unavailable supplements. Each optional supplement has one five-second budget. not_found means the ID did not resolve; adult_content means it exists but requires opt-in. Adult direct relations are omitted without opt-in, with a count
  • full_text: true returns the complete result as fenced JSON; by default the synopsis is a 500-character preview and tags and relations are shortened, with counts of what was omitted

anime_get_relations tool

  • Walk a franchise from an AniList id up to max_depth hops (default 2, max 4). Adult roots require include_adult: true; without opt-in, adult relations are omitted and not traversed
  • Returns main and supplementary entries with country of origin, season year and episode/chapter counts, ordered by relation priority then year. not_found means the root ID did not resolve; adult_content identifies an adult root without opt-in
  • depth, parent_id, relation_to_parent, and path show the shortest route to each entry. relation_to_root is set only for entries linked directly to the root, and is null otherwise. Entries at the hop limit are returned without their own relations; depth_reached is the deepest hop returned

anime_get_schedule tool

  • season mode requires season and season_year; upcoming uses days_ahead (default 7, max 30). Page with page/per_page (max 50); adult titles require include_adult: true
  • Returns UTC ISO 8601 airing times and time_until_airing_seconds. Upcoming text includes total episodes when known and uses minutes below one hour. Follow has_next_page; total_results is exact only on the final season page. invalid_season and conflicting_inputs identify invalid mode inputs

anime_find_characters tool

  • Supply exactly one of media id, character_name, character_id, voice_actor_name, or voice_actor_id. language filters only media cast lookups; use JAPANESE for Japanese credits only. per_page defaults to 10 and is capped at 25; omitted language retains every returned dub language
  • Returns cast, voice actors, or media appearances according to mode. Name lookups retain the selected hit and offer other_matches from the first suggestion page, with independent continuation and availability. Exact person IDs select a known character or staff member directly. truncated: true carries next-page guidance for capped cast lists; media_not_found/not_found distinguish an unknown media ID from an unmatched person
  • voice_actor_data_available: false means the provider had no voice actor data, as opposed to an empty list. full_text: true returns every role on the page and the full biography as fenced JSON; by default biographies are 500-character previews and staff roles stop at 20, with counts of what was omitted

anime_get_recommendations tool

  • Fetch recommendations for an AniList id with source: "anilist" (default) or source: "jikan"; optional liked_aspects is echoed unchanged. AniList pages its recommendations and adds matching MAL votes. Jikan deduplicates its supplied list by maximum votes, orders votes descending/MAL ID ascending, and locally pages candidates with page/per_page (max 25) before resolving that slice through AniList. Adult roots and entries require include_adult: true; unresolved candidates remain omitted. has_next_page follows the selected source even on fully filtered pages, without backfill. Jikan does not guarantee a global ranking or a stable snapshot across calls
  • Both surfaces report source and jikan_status (available, unavailable, or not_applicable when the source lacks a MAL ID), plus separate anilist_rating, jikan_votes, and item sources. Jikan mode uses null anilist_rating and sources: ["jikan"]. Optional annotation failures retain AniList results; selected Jikan/resolution failures return retry-or-switch guidance. truncated: true supplies continuation with the same source; not_found means the source ID did not resolve, while valid empty pages succeed
  • Every recommendation exposes is_adult. Identified adult omissions receive a counted notice; unresolved MAL candidates are not assumed to be adult

anime_get_rankings tool

  • Rank ANIME or MANGA in top/trending; seasonal and season/year filters apply only to ANIME (anime_only_season otherwise). Genre/tag/format filters and page/per_page (max 50) remain available. Adult titles require include_adult: true
  • Entries carry 1-based rank, country_of_origin, and their broadcast season; the response's season_label describes the requested ranking. Empty first-page genre results can suggest a matching AniList tag. Follow has_next_page; total_results is exact on a nonempty final page or zero on an empty first page, and null otherwise. Seasonal mode takes season/season_year together or neither for the current season (invalid_season otherwise)

anime_get_studio tool

  • Identify a studio with exactly one of name or id; IDs come from anime_get_media.studios[].id or a studio lookup's studio_id. Sort by popularity, score, or release date and page with page/per_page (max 25). Set main_only: true to filter to main-studio credits before paging
  • Returns one row per distinct title within the page, with is_main_studio identifying main credits. Follow has_next_page; total_titles is exact only when the whole filmography fits on page 1. not_found means the studio did not resolve

anime://media/{id} resource

  • Read a compact application/json media record using an AniList id from anime_search_media or anime_get_media
  • The ID must be a whole number from 1 to 2147483647; anything else fails with invalid_id before any upstream call
  • Returns title variants, synopsis, scores, genres, streaming count, and cover image; use anime_get_media for tags, studios, streaming links, and relations
  • Adult IDs return adult_content; use anime_get_media with include_adult: true for adult detail. streaming_count counts the same merged destinations as the media tool

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Anime/manga-specific:

  • Three-source architecture: AniList GraphQL (primary), Jikan v4 REST (MAL scores + recommendations), Kitsu JSON:API (streaming links with sub/dub language detail)
  • ID reconciliation via AniList's idMal bridge — no cross-source ID guessing
  • Franchise relation graph traversal with heuristic ordering by relation-type priority, then season year
  • Rate-limit-aware service layer: AniList 30 req/30s with automatic backoff; Jikan 350ms floor between calls
  • Keyless by design — all three sources are public and require no API credentials

Agent-friendly output:

  • Dual scores surfaced separately — AniList meanScore (0–100) and MAL score (0–10) with population size (scored_by) so agents can reason about weight; never blended into a composite
  • Spoiler flags — the tag summary hides spoiler/adult tags; structured output and full_text: true carry all tags with their flags
  • Supplement provenance — anime_get_media.data_sources reports whether AniList, MAL/Jikan, and Kitsu data was retrieved; an unavailable supplement leaves its flag false
  • UTC timestamps throughout; season labels echoed (WINTER 2024) to avoid the winter/spring/summer/fall boundary footgun

Getting started

No API keys required — all three upstream sources (AniList, Jikan, Kitsu) are keyless public APIs.

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "anime-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/anime-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "anime-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/anime-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "anime-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/anime-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

  • Bun v1.4.4 or higher (or Node.js v24+). No API keys needed.

Installation

  1. Clone the repository:
git clone https://github.com/cyanheads/anime-mcp-server.git
  1. Navigate into the directory:
cd anime-mcp-server
  1. Install dependencies:
bun install
  1. Configure environment (optional):
cp .env.example .env
# edit .env if you want to change transport or log level

Configuration

No server-specific env vars are required. All framework variables are optional with sensible defaults.

| Variable | Description | Default | |:---------|:------------|:--------| | MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio | | MCP_HTTP_PORT | Port for HTTP server. | 3010 | | MCP_HTTP_HOST | Hostname for HTTP server. | 127.0.0.1 | | MCP_HTTP_ENDPOINT_PATH | Endpoint path for the MCP server. | /mcp | | MCP_SESSION_MODE | Session mode: auto, stateful, or stateless. | stateless | | MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none | | MCP_LOG_LEVEL | Log level (RFC 5424): debug, info, notice, warning, error. | info | | LOG_TOOL_FAILURE_PAYLOADS | Log failed calls' arguments and results, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). Secrets inside free-form values are not redacted. | false | | OTEL_ENABLED | Enable OpenTelemetry instrumentation. | false |

See .env.example for the full list of optional overrides.


Running the server

Local development

  • Build and run:

    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:stdio
    # or
    bun run start:http
  • Run checks and tests:

    bun run devcheck   # Lint, format, typecheck, security
    bun run test       # Vitest test suite
    bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t anime-mcp-server .
docker run --rm -p 3010:3010 anime-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/anime-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.


Project structure

| Directory | Purpose | |:----------|:--------| | src/index.ts | createApp() entry point — registers tools, resources, and inits services. | | src/mcp-server/tools | Tool definitions (*.tool.ts). | | src/mcp-server/resources | Resource definitions (*.resource.ts). | | src/services/anilist | AniList GraphQL client — primary source for all queries. | | src/services/jikan | Jikan v4 REST client — MAL scores and recommendations. | | src/services/kitsu | Kitsu JSON:API client — streaming links with sub/dub language detail. | | tests/ | Unit and integration tests mirroring src/. | | skills/ | Published caller guide, available through plugins and MCP skill discovery. | | changelog/ | Per-version changelog files (changelog/<minor>.x/<version>.md). |


Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

  • Handlers throw, framework catches — no try/catch in tool logic
  • Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
  • Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
  • Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
  • AniList is primary — supplement failures (Jikan, Kitsu) degrade gracefully via Promise.allSettled

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.