\n\n# ani-mcp\n\n[](https://www.npmjs.com/package/ani-mcp)\n[](https://www.npmjs.com/package/ani-mcp)\n[](https://github.com/gavxm/ani-mcp/actions/workflows/ci.yml)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/gavxm/ani-mcp/releases/latest)\n\nA smart [MCP](https://modelcontextprotocol.io) server for [AniList](https://anilist.co) that understands your anime and manga taste - not just raw API calls.\n\n## What makes this different\n\nMost AniList integrations mirror the API 1:1. ani-mcp adds an intelligence layer on top:\n\n- **Taste profiling** - builds a model of your preferences from your completed list\n- **Personalized picks** - \"what should I watch next?\" based on your taste, mood, and seasonal lineup\n- **Compatibility** - compare taste between two users\n- **Sequel alerts** - find sequels airing this season for shows you've finished\n- **Watch order** - franchise chain traversal for long-running series\n- **Session planning** - \"I have 90 minutes, what should I watch?\" from your current list\n- **Year in review** - your watching/reading stats wrapped up\n\nPlus the essentials: search, details, trending, seasonal browsing, list management, social features, and community recommendations. All search and browse tools support pagination for browsing beyond the first page of results.\n\n## Try it in 30 seconds\n\nNo account needed. Works with any MCP-compatible client.\n\n### Claude Desktop\n\nAdd to your config file (`Settings > Developer > Edit Config` or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n \"mcpServers\": {\n \"anilist\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"ani-mcp\"]\n }\n }\n}\n```\n\nRestart Claude Desktop after saving.\n\nAlternatively, download `ani-mcp.mcpb` from the [latest release](https://github.com/gavxm/ani-mcp/releases/latest) and install via `Settings > Extensions`.\n\n### Claude Code\n\n```sh\nclaude mcp add ani-mcp -- npx -y ani-mcp\n```\n\n### Personalized features\n\nAdd your username for recommendations, taste profiling, and list management:\n\n```json\n{\n \"mcpServers\": {\n \"anilist\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"ani-mcp\"],\n \"env\": {\n \"ANILIST_USERNAME\": \"your_username\"\n }\n }\n }\n}\n```\n\nFor write operations (updating progress, scoring, list edits), also add `ANILIST_TOKEN`. See [Environment Variables](#environment-variables) for details.\n\n## Environment Variables\n\n| Variable | Required | Description |\n| --- | --- | --- |\n| `ANILIST_USERNAME` | No | Default username for list and stats tools. Can also pass per-call. |\n| `ANILIST_TOKEN` | No | AniList OAuth token. Required for write operations and private lists. |\n| `ANILIST_TITLE_LANGUAGE` | No | Title preference: `english` (default), `romaji`, or `native`. |\n| `ANILIST_SCORE_FORMAT` | No | Override score display: `POINT_100`, `POINT_10_DECIMAL`, `POINT_10`, `POINT_5`, `POINT_3`. |\n| `ANILIST_NSFW` | No | Set to `true` to include adult content in results. Default: `false`. |\n| `ANILIST_MOOD_CONFIG` | No | JSON object to add or override mood keywords. See [Mood config](#mood-config). |\n| `DEBUG` | No | Set to `true` for debug logging to stderr. |\n| `MCP_TRANSPORT` | No | Set to `http` for HTTP Stream transport. Default: stdio. |\n| `MCP_PORT` | No | Port for HTTP transport. Default: `3000`. |\n| `MCP_HOST` | No | Host for HTTP transport. Default: `localhost`. |\n\n## Tools\n\n### Search & Discovery\n\n| Tool | Description |\n| --- | --- |\n| `anilist_search` | Search anime/manga by title with genre, year, and format filters |\n| `anilist_details` | Full details, relations, and recommendations for a title |\n| `anilist_seasonal` | Browse a season's anime lineup |\n| `anilist_trending` | What's trending on AniList right now |\n| `anilist_genres` | Browse top titles in a genre with optional filters |\n| `anilist_genre_list` | List all valid genres and content tags |\n| `anilist_recommendations` | Community recommendations for a specific title |\n\n### Lists & Stats\n\n| Tool | Description |\n| --- | --- |\n| `anilist_list` | A user's anime/manga list, filtered by status |\n| `anilist_lookup` | Check if a specific title is on a user's list |\n| `anilist_stats` | Watching/reading statistics, top genres, score distribution |\n\n### Intelligence\n\n| Tool | Description |\n| --- | --- |\n| `anilist_taste` | Generate a taste profile from your completed list |\n| `anilist_pick` | Personalized \"what to watch next\" from your backlog, seasonal lineup, or discovery pool |\n| `anilist_compare` | Compare taste compatibility between two users |\n| `anilist_wrapped` | Year-in-review summary |\n| `anilist_explain` | \"Why would I like this?\" - score a title against your taste profile |\n| `anilist_similar` | Find titles similar to a given anime or manga |\n| `anilist_sequels` | Sequels airing this season for titles you've completed |\n| `anilist_watch_order` | Viewing order for a franchise |\n| `anilist_session` | Plan a viewing session within a time budget |\n| `anilist_mal_import` | Import a MyAnimeList user's list and generate recommendations |\n| `anilist_kitsu_import` | Import a Kitsu user's list and generate recommendations |\n\n### Cards\n\n| Tool | Description |\n| --- | --- |\n| `anilist_taste_card` | Generate a shareable taste profile card as a PNG image |\n| `anilist_compat_card` | Generate a compatibility card comparing two users as a PNG image |\n\n
\n \n \n
\n\n### Info\n\n| Tool | Description |\n| --- | --- |\n| `anilist_staff` | Staff credits and voice actors for a title |\n| `anilist_staff_search` | Search for a person by name and see all their works |\n| `anilist_studio_search` | Search for a studio and see their productions |\n| `anilist_schedule` | Airing schedule and next episode countdown |\n| `anilist_airing` | Upcoming episodes for titles you're currently watching |\n| `anilist_characters` | Search characters by name with appearances and VAs |\n| `anilist_whoami` | Check authentication status and score format |\n\n### Social\n\n| Tool | Description |\n| --- | --- |\n| `anilist_profile` | View a user's profile, bio, favourites, and stats |\n| `anilist_feed` | Recent activity from a user's feed |\n| `anilist_reviews` | Community reviews for a title |\n| `anilist_favourite` | Toggle favourite on anime, manga, character, staff, or studio |\n| `anilist_activity` | Post a text activity to your feed |\n| `anilist_group_pick` | Find anime/manga for a group to watch together |\n| `anilist_shared_planning` | Find overlap between two users' planning lists |\n| `anilist_follow_suggestions` | Rank followed users by taste compatibility |\n| `anilist_react` | Like or reply to an activity |\n\n### Analytics\n\n| Tool | Description |\n| --- | --- |\n| `anilist_calibration` | Per-genre scoring bias vs community consensus |\n| `anilist_drops` | Drop pattern analysis - genre/tag clusters and median drop point |\n| `anilist_evolution` | How your taste shifted across 2-year time windows |\n| `anilist_completionist` | Franchise completion tracking via relation graph |\n| `anilist_seasonal_stats` | Per-season pick/finish/drop rates |\n| `anilist_pace` | Estimated completion date for currently watching titles |\n\n### Write (requires `ANILIST_TOKEN`)\n\n| Tool | Description |\n| --- | --- |\n| `anilist_update_progress` | Update episode or chapter progress |\n| `anilist_add_to_list` | Add a title to your list with a status |\n| `anilist_rate` | Score a title (0-10) |\n| `anilist_delete_from_list` | Remove an entry from your list |\n| `anilist_undo` | Undo the last write operation |\n| `anilist_unscored` | List completed but unscored titles for batch scoring |\n| `anilist_batch_update` | Bulk filter + action on list entries (dry-run default) |\n\n## Resources\n\nMCP resources provide context to your AI assistant without needing a tool call. Clients that support resources can automatically include this information in conversations.\n\n| Resource | Description |\n| --- | --- |\n| `anilist://profile` | Your AniList profile with bio, stats, and favourites |\n| `anilist://taste/{type}` | Taste profile (genre weights, themes, scoring patterns) for ANIME or MANGA |\n| `anilist://list/{type}` | Currently watching/reading entries with progress and scores |\n\n## Prompts\n\nPre-built conversation starters that clients can offer as quick actions.\n\n| Prompt | Description |\n| --- | --- |\n| `setup` | Walk through connecting your AniList account step by step |\n| `seasonal_review` | Review this season's anime against your taste profile |\n| `what_to_watch` | Plan what to watch now with optional mood and time budget |\n| `roast_my_taste` | Get a humorous roast of your anime taste |\n| `compare_us` | Compare your taste with another user |\n| `year_in_review` | Your anime/manga year in review |\n| `explain_title` | Why would you like (or dislike) a specific title? |\n| `find_similar` | Find titles similar to one you enjoyed |\n\n## Examples\n\nHere are some things you can ask your AI assistant once ani-mcp is connected:\n\n**\"What should I watch next?\"**\nUses `anilist_pick` to analyze your completed list, build a taste profile, and recommend titles from your Planning list ranked by how well they match your preferences.\n\n**\"I want something dark and psychological\"**\nUses `anilist_pick` with mood filtering to boost titles matching that vibe and penalize mismatches.\n\n**\"What's good this season?\"**\nUses `anilist_pick` with `source: SEASONAL` to rank currently airing anime against your taste profile.\n\n**\"I have 90 minutes, what should I watch tonight?\"**\nUses `anilist_session` to pick from your currently watching list and fill a time budget with the best-matching episodes.\n\n**\"Any sequels airing for stuff I've finished?\"**\nUses `anilist_sequels` to cross-reference your completed list with this season's lineup.\n\n**\"What order do I watch Fate in?\"**\nUses `anilist_watch_order` to traverse the franchise relation graph and produce a numbered viewing order.\n\n**\"Compare my taste with username123\"**\nUses `anilist_compare` to find shared titles, compute a compatibility score, and highlight biggest disagreements.\n\n**\"Why would I like Vinland Saga?\"**\nUses `anilist_explain` to score a title against your taste profile, breaking down genre affinity and theme alignment.\n\n**\"Show me my anime year in review\"**\nUses `anilist_wrapped` to summarize everything you watched in a given year.\n\n## Mood config\n\n`anilist_pick` and `anilist_session` accept a freeform `mood` string. Built-in keywords include: dark, chill, hype, action, romantic, funny, brainy, sad, scary, epic, wholesome, intense, mystery, fantasy, scifi, trippy, nostalgic, artistic, competitive, cozy.\n\nTo add or override keywords, set `ANILIST_MOOD_CONFIG` as a JSON object:\n\n```json\n{\n \"ANILIST_MOOD_CONFIG\": \"{\\\"cozy\\\":{\\\"boost\\\":[\\\"Slice of Life\\\",\\\"Iyashikei\\\"],\\\"penalize\\\":[\\\"Horror\\\"]},\\\"mykeyword\\\":{\\\"boost\\\":[\\\"Romance\\\"],\\\"penalize\\\":[]}}\"\n}\n```\n\nEach key is a mood keyword mapping to `{ boost: string[], penalize: string[] }` arrays of AniList genres and tags.\n\n## Privacy\n\nSee [PRIVACY.md](PRIVACY.md) for details. In short: ani-mcp runs locally, sends requests only to the AniList API, stores nothing, and collects no analytics.\n\n## Docker\n\n```sh\ndocker build -t ani-mcp .\ndocker run -e ANILIST_USERNAME=your_username ani-mcp\n```\n\nRuns on port 3000 with HTTP Stream transport by default.\n\n## Build from Source\n\n```sh\ngit clone https://github.com/gavxm/ani-mcp.git\ncd ani-mcp\nnpm install\nnpm run build\nnpm test\n```\n\n## Support\n\nBug reports and feature requests: [GitHub Issues](https://github.com/gavxm/ani-mcp/issues)\n\n## License\n\n[MIT](LICENSE)\n",
"bytes": 12062,
"sha": "e4a9d801eed8577ba22415b505503bef568268deb9e4119538a843bdca9c0d49",
"repo_slug": "gavmason/ani-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_gavmason_ani_mcp_161f71f6/readme"
}
![\"ani-mcp\"](\"assets/icon.svg\"){kind=icon}
\n![\"Taste](\"assets/taste-card.png\")
\n ![\"Compatibility](\"assets/compat-card.png\")
\n