anilist-mcp-server

# AniList MCP Server

[![npm version](https://img.shields.io/npm/v/anilist-mcp-server.svg)](https://www.npmjs.com/package/anilist-mcp-server)
[![CI](https://github.com/Grinv/anilist-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/Grinv/anilist-mcp-server/actions/workflows/ci.yml)
[![license: MIT](https://img.shields.io/npm/l/anilist-mcp-server.svg)](LICENSE)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.Grinv%2Fanilist--mcp--server-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Grinv/anilist-mcp-server&version=latest)
[![anilist-mcp-server MCP server](https://glama.ai/mcp/servers/Grinv/anilist-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/Grinv/anilist-mcp-server)

An [MCP](https://modelcontextprotocol.io) server for **[AniList](https://anilist.co)**.
It works with any MCP-compatible client or agent (Claude Desktop/Code, Cursor,
VS Code, Cline, Continue, and others) — the server 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 — you can skip straight to
[Install](#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 →](#connect-your-anilist-account)), 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?"
```

**With your AniList account** (after a one-time `login_anilist`; see
[Connect your AniList account](#connect-your-anilist-account)):

```
"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?"
```

## Tools

| Tool                                                                                                  | Auth  |
| ----------------------------------------------------------------------------------------------------- | ----- |
| `get_genres`, `get_media_tags`, `get_site_statistics`, `get_studio`                                   | none  |
| `get_media`, `get_media_statistics`, `get_media_characters`, `get_media_staff`                        | none  |
| `get_media_reviews`, `get_media_relations`, `get_anime_schedule`                                      | none  |
| `get_character`, `get_staff`, `get_todays_birthdays`                                                  | none  |
| `get_recommendation`, `get_recommendations_for_media`                                                 | none  |
| `search_media`, `search_character`, `search_staff`, `search_studio`, `search_user`, `search_activity` | none  |
| `search_thread`, `get_thread`, `get_thread_comments`                                                  | none  |
| `get_user_profile`, `get_user_stats`, `get_full_user_info`, `get_user_recent_activity`                | none  |
| `get_activity`, `get_user_activity`                                                                   | none  |
| `get_user_list`                                                                                       | none  |
| `favourite`                                                                                           | token |
| `add_list_entry`, `update_list_entry`, `remove_list_entry`                                            | token |
| `post_text_activity`, `post_message_activity`, `delete_activity`                                      | token |
| `post_thread`, `post_thread_comment`, `delete_thread`, `delete_thread_comment`                        | token |
| `get_authorized_user`, `follow_user`, `update_user`                                                   | token |
| `get_notifications`                                                                                   | token |
| `login_anilist`, `submit_anilist_redirect`                                                            | login |

`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`**](https://github.com/Grinv/anilist-mcp-server/releases/latest/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](#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`](https://www.npmjs.com/package/anilist-mcp-server).
Add it to your client's MCP config (Claude Desktop/Code, Cursor, VS Code, Cline, …):

```json
{
  "mcpServers": {
    "anilist": {
      "command": "npx",
      "args": ["-y", "anilist-mcp-server"],
      "env": {
        "ANILIST_CLIENT_ID": "...",
        "ANILIST_CLIENT_SECRET": "..."
      }
    }
  }
}
```

Or with the Claude Code CLI:

```sh
claude mcp add anilist -e ANILIST_CLIENT_ID=... -e ANILIST_CLIENT_SECRET=... -- npx -y anilist-mcp-server
```

### From source

```sh
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 will 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](docs/auth.md) for the full login walkthrough and
[docs/clients.md](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.

**Step 1 — Register an AniList app (one minute).**

1. Go to <https://anilist.co/settings/developer> and click **Create New Client**.
2. **Name:** anything.
3. **Redirect URL:** enter exactly
   ```
   http://localhost:8082/callback
   ```
   _(If port 8082 is already used on your machine, pick another port here and set
   `ANILIST_OAUTH_PORT` to the same number — see [Configuration](#configuration).)_
4. Save. Copy the **Client ID** and **Client Secret**.

**Step 2 — Give the credentials to the server.**

```json
"env": { "ANILIST_CLIENT_ID": "...", "ANILIST_CLIENT_SECRET": "..." }
```

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** the moment 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 ye