An MCP server for AniList.
It works with any MCP-compatible client or agent (Claude Desktop/Code, Cursor,
VS Code, Cline, Continue, and others). It speaks the standard MCP
stdio protocol.
What it does
Talks directly to AniList's public GraphQL API (https://graphql.anilist.co):
Reads (no credentials needed). Search and browse anime/manga,
characters, staff, studios; genres/tags; recommendations; forum threads;
activity feeds; public/unlisted user profiles and lists.
Your own AniList account (requires a one-time login). Manage your own
anime/manga list (add/update/remove entries), favourites, follows, your
notifications, and post/delete your own activity and threads.
What you need (and what it gets you)
Nothing is required to get started, so you can skip straight to
Install. Everything below is optional:
You set...
You get...
(nothing)
Search, details, genres/tags, recommendations, threads, activity, public profiles/lists. Works immediately.
An AniList Client ID + Client Secret (2 minutes, free →), plus running login_anilist once
Everything above, plus your own AniList account: manage your list, favourites, follows, activity, and threads.
Without a login, the personal/mutation tools reply with a clear message
telling you how to get one; everything else keeps working regardless.
Example queries
Once it's connected, just ask your agent in natural language.
No credentials needed:
"Search for the anime Frieren and show its score, genres and synopsis."
"What recommendations does AniList have for fans of Steins;Gate?"
"Show me today's birthday characters."
"What genres and tags does AniList use for anime?"
"Show the public profile and stats for user <username>."
"What's in <username>'s AniList anime list marked as watching?"
"Add Frieren to my AniList plan-to-watch list."
"Set Cowboy Bebop to completed on my AniList with a score of 9."
"Follow user <username> for me."
"Post a text update to my AniList activity feed."
"What are my unread AniList notifications?"
token = needs an AniList login (run login_anilist once).
Prompts
Reusable multi-step plans your client can offer as one-click flows:
recommend_similar, seasonal_overview, hidden_gems, catch_up_activity,
check_notifications.
Install
As an .mcpb bundle (one-click, e.g. Claude Desktop)
Download anilist-mcp-server.mcpb
(always the latest release) and open it with your MCP client. It prompts for an optional
AniList Client ID and Client Secret. Set them and run the login_anilist tool to
enable the personal-list/social tools (see
Connect your AniList account). Leave them
blank to use just the credential-free read tools.
Via npx (no install)
Published on npm as anilist-mcp-server.
Add it to your client's MCP config (Claude Desktop/Code, Cursor, VS Code, Cline, …):
git clone https://github.com/Grinv/anilist-mcp-server
cd anilist-mcp-server
npm ci
npm run build
This produces a self-contained dist/index.js. Point your client at it the same
way as above, swapping "command": "npx", "args": ["-y", "anilist-mcp-server"]
for "command": "node", "args": ["/absolute/path/to/anilist-mcp-server/dist/index.js"]
(and npx -y anilist-mcp-server for node /absolute/path/to/anilist-mcp-server/dist/index.js
in the CLI form).
The env block (shown above for both install methods) is optional: omit it to use only the credential-free read
tools; the personal/mutation tools return a clear error until you log in.
To enable them, set ANILIST_CLIENT_ID + ANILIST_CLIENT_SECRET and run the
login_anilist tool once (a one-time browser authorization; the token is
then stored and reused). The server does not read a .env file, so pass
config via this env block (or your shell environment). See
docs/auth.md for the full login walkthrough and
docs/clients.md for more clients.
Connect your AniList account
The search/browse tools work with no setup. To use the personal/mutation
tools, authorize your account once. It takes about two minutes.
Restart the server/client so it picks up the values.
Step 3: Log in (one click).
In your assistant, run the login_anilist tool (or just say "log in to
AniList"). It replies with a link. Open the link, sign in to AniList, and
click Approve.
Running locally (Claude Desktop, or Claude Code on your own machine):
login finishes automatically as soon as you click Approve. Confirm with
"show my AniList profile" (get_authorized_user).
Running on a remote/SSH/headless host: after clicking Approve your
browser lands on a page that won't load; that's expected. Copy the full
address from the browser's address bar (it contains ?code=…) and give it
to the submit_anilist_redirect tool to finish.
That's it. The token is saved locally (~/.config/anilist-mcp-server/tokens.json,
0600). AniList access tokens don't expire for about a year and there's no
refresh mechanism, so you'll need to run login_anilist again once it does.
Prefer no interactive step? Pre-set a standalone ANILIST_ACCESS_TOKEN
instead. See docs/auth.md.
Configuration
All configuration is via environment variables, all optional; without
credentials the read tools still work.
Your AniList app's Client Secret, paired with the Client ID above.
ANILIST_ACCESS_TOKEN
Advanced, optional. Pre-supply a token instead of running login_anilist. See docs/auth.md.
ANILIST_TOKEN_STORE
Override where the login token is saved on disk (default: your OS's config folder).
ANILIST_OAUTH_PORT
Only needed if port 8082 is already in use (see step 1 of the account walkthrough).
LOG_LEVEL
How much the server logs: debug | info | warn | error | silent (default info).
Tuning (rarely needed)
Variable
Purpose
ANILIST_MIN_INTERVAL_MS
Min spacing between AniList calls (default 2100, i.e. ~30/min, since AniList's API is currently in a documented degraded state; see docs/api-references.md). Set to 0 to disable client-side throttling.
CACHE_TTL_MS
TTL for the in-memory read cache (default 300000 = 5 min).
HTTP_TIMEOUT_MS, HTTP_RETRIES
Per-request timeout (default 15000) and retry attempts for transient failures (default 2).
ANILIST_GRAPHQL_URL, ANILIST_OAUTH_BASE_URL
Override upstream base URLs.
Provide these in your MCP client config's env block (the server does not
read a .env file). See docs/auth.md for how to obtain the
credentials, and docs/clients.md for client configuration
snippets.
NSFW content
NSFW (adult) results are not filtered by default; the server returns
whatever AniList provides. search_media accepts an optional sfw
parameter; set sfw: true to exclude adult entries.
Development
npm run build # type-check + bundle to dist/
npm test # node:test suite (mocked, offline)
npm run test:coverage
npm run lint
npm run format
npm run check:api # live health-check of the AniList GraphQL endpoint
npm run inspector # run under the MCP Inspector
Runtime requires Node ≥ 20.11. See AGENTS.md for contributor/agent
guidance, including why this server exists and how it avoids the upstream bug
that motivated building it.
Updating
To be notified of new versions, click Watch → Releases on GitHub.
.mcpb bundle: download the new anilist-mcp-server.mcpb from the
releases page and
reinstall it in your client (it replaces the old version).
npx: unpinned npx -y anilist-mcp-server fetches the latest on the next run.
From source:git pull && npm ci && npm run build.
See the CHANGELOG for what changed in each release.
Attribution and terms
This is an unofficial project and is not affiliated with or endorsed by
AniList. All data comes from the public AniList GraphQL API;
personal-account operations use your own AniList account and token. Use is
subject to AniList's Terms of Service.
Privacy Policy
This server runs locally on your machine and has no telemetry of its own.
Personal/mutation tools act on your real AniList account (list, favourites,
follows, posts, account settings) using a token you supply. See
PRIVACY.md for the full details on data collection, what gets
sent where, caching/token storage and retention, and contact info.
Security
This is the broadest write/social tool surface of this project's sibling
servers: list mutations, favourites, follows, and posting/deleting activity,
threads, and comments, all on your real AniList account. See
SECURITY.md for the full mutating-tool inventory, token
storage/handling, credential redaction, and how to report a vulnerability.
