animeport

animeport

animeport answers questions about anime and manga using AniList: what a series is about and how it scored, who made it, which characters and staff share a birthday today, what a given user is watching or reading, and what fans of one title tend to recommend next. Every answer comes from AniList's public GraphQL API.

This package is a clean-room rebuild, and a labelled core subset: it covers 20 of the 42 tools documented for the original AniList MCP server. The omitted tools are listed under "Scope" below.

How it talks to the service

Each tool sends exactly one GraphQL query by POST to the AniList API and returns the response's data payload:

# Optional: raises rate limits / unlocks authenticated reads on AniList.
export ANILIST_TOKEN="your token"
# Optional override (default: https://graphql.anilist.co)
export ANILIST_API_URL="https://graphql.anilist.co"

The token is genuinely optional. With no token set, requests go out keyless, which AniList accepts for these read tools — nothing fails just because ANILIST_TOKEN is missing. When AniList answers with a GraphQL errors array, the call fails with the first error's message; an upstream HTTP error is reported with its status and a body excerpt.

Field-selection note: the original project's README documents the tools and their purposes, not the GraphQL field selections. The queries here are fresh, sensible reconstructions chosen for each tool's stated purpose, not copies of the original's queries.

Install

npx @reneturcios/animeport search_anime '{"search":"Frieren"}'

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/animeport

The container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead.

CLI

The CLI mirrors the tools: one subcommand per tool, taking its arguments as a single JSON object.

animeport get_genres '{}'
animeport search_anime '{"search":"Frieren","perPage":5}'
animeport get_anime '{"id":154587}'
animeport get_todays_birthday_characters '{}'
animeport get_user_anime_list '{"username":"someone","status":"CURRENT"}'
animeport get_recommendations_for_media '{"mediaId":154587}'
animeport --version

Exit codes: 0 on success, 1 on an API or validation error (the error names the problem), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/animeport mcp

MCP client configuration:

{
  "mcpServers": {
    "animeport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/animeport", "mcp"],
      "env": { "ANILIST_TOKEN": "your token (optional)" }
    }
  }
}

Tools

Tool	Input	What it does
get_genres	—	Get the list of available genres on AniList.
get_media_tags	—	Get the list of available media tags on AniList.
get_studio	id and/or name (at least one, validated locally)	Get details of a studio by AniList ID or name.
search_anime	search, page, perPage, genre, seasonYear (all optional)	Search for anime by title, genre, or season year.
search_manga	search, page, perPage, genre, seasonYear (all optional)	Search for manga by title, genre, or season year.
search_character	search (required), page, perPage	Search for characters by name.
search_staff	search (required), page, perPage	Search for staff by name.
search_studio	search (required), page, perPage	Search for studios by name.
search_user	search (required), page, perPage	Search for AniList users by username.
get_anime	id (required)	Get detailed information about an anime by AniList ID.
get_manga	id (required)	Get detailed information about a manga by AniList ID.
get_character	id (required)	Get detailed information about a character by AniList ID.
get_staff	id (required)	Get detailed information about a staff member by AniList ID.
get_todays_birthday_characters	—	Get characters whose birthday is today.
get_todays_birthday_staff	—	Get staff members whose birthday is today.
get_user_anime_list	username (required), status	Get a user's anime list, optionally filtered by status.
get_user_manga_list	username (required), status	Get a user's manga list, optionally filtered by status.
get_user_profile	username (required)	Get a user's AniList profile.
get_user_stats	username (required)	Get a user's activity statistics.
get_recommendations_for_media	mediaId (required), page, perPage	Get recommendations for a media entry by its AniList ID.

Scope

Omitted from this core subset: get_site_statistics, get_activity, get_user_activity, post_message_activity, post_text_activity, delete_activity, add_list_entry, remove_list_entry, update_list_entry, favourite_anime, favourite_manga, favourite_character, favourite_staff, favourite_studio, get_recommendation, get_thread, get_thread_comments, delete_thread, get_full_user_info, get_authorized_user, follow_user, and update_user. The omitted set is deliberately the login, write, favourite, and thread surface; animeport is read-only by design. The catalogue data itself is AniList's; this package reproduces the tool surface and the request/response handling, not AniList's database.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.