# AniList MCP server

[![CI](https://github.com/nochinsky/anilist-manager-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nochinsky/anilist-manager-mcp/actions/workflows/ci.yml)

Manage your AniList anime and manga library through a standard MCP server. Works with compatible AI harnesses independently of the model provider. Local stdio is the default; no hosted service, plugin registration or database is needed.

## Install and connect

Requires **Node.js 22.19+**. Install the compiled GitHub release with npm:

```sh
npm install --global https://github.com/nochinsky/anilist-manager-mcp/releases/download/v1.0.0/anilist-manager-mcp-1.0.0.tgz
anilist-mcp setup
```

Paste your **AniList access token** at the hidden prompt. Setup verifies it against your AniList profile and saves it outside the project. It never modifies your library. On Windows the token is encrypted with DPAPI; on macOS/Linux it is stored in an owner-only file. You can alternatively provide ANILIST_ACCESS_TOKEN using your harness's private environment settings.

Choose your installed harness:

```sh
# Codex
anilist-mcp connect codex

# Claude Code
anilist-mcp connect claude

# Pi coding agent (current version with built-in MCP)
anilist-mcp connect pi
```

Each command registers the local server named **anilist** using the actual installed Node and server paths. It uses that harness's official `mcp add` command and its user-level configuration. If an anilist entry already exists, the harness may replace it or ask you to resolve it. Restart/reload the harness, enable its MCP tools, and ask: **“Use AniList to show my profile and currently watching list.”**

The harness starts the server for you. No extra running terminal, tunnel or second login is needed. All three harnesses must be installed separately; this package does not install or change your model provider.

If the command is not found after global installation, reopen your terminal and check your npm global bin directory is on PATH.

### Other install options

Install directly from the tagged GitHub source (requires Git and allows the build hook):

```sh
npm install --global github:nochinsky/anilist-manager-mcp#v1.0.0
```

Or develop from a checkout:

```sh
git clone https://github.com/nochinsky/anilist-manager-mcp.git
cd anilist-manager-mcp
npm ci
npm run setup
npm run build
node dist/cli.js connect codex
```

**Publishing to the npm registry is optional.** The release archive and GitHub install already work with npm. This project has not been published to the registry; do not use `npx anilist-manager-mcp` expecting a registry release.

## Manual harness configuration

If you prefer editing configuration yourself, these commands print snippets containing this installation's exact paths, with no tokens:

```sh
anilist-mcp config codex
anilist-mcp config claude
anilist-mcp config pi
anilist-mcp config json
```

| Harness | Where to put the generated settings | Check the connection |
| --- | --- | --- |
| Codex | Merge the generated TOML into `~/.codex/config.toml` | `codex mcp list`, then `/mcp` in a new session |
| Claude Code | Merge the generated mcpServers entry into private user configuration (`~/.claude.json`), preserving other entries; using `connect claude` is easier | `claude mcp get anilist`, then `/mcp` |
| Pi | Merge the generated mcpServers entry into `~/.pi/agent/mcp.json` | `pi mcp list`, then `/mcp` or `/reload` |
| Other stdio MCP client | Its local MCP settings; use the JSON entry's command and args | The client's tool-discovery view |

`~` means your home directory. The config generator handles Windows paths and spaces. It registers `node` directly so npm banners cannot contaminate the MCP protocol. The current Pi built-in MCP requires no adapter; older Pi versions should be upgraded or connected through a separately installed MCP adapter.

Official setup references: [Codex](https://learn.chatgpt.com/docs/extend/mcp), [Claude Code](https://code.claude.com/docs/en/mcp), [Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/mcp.md).

## Tools

| Read | Write |
| --- | --- |
| get_my_anilist_profile | add_anime_to_list |
| get_my_anime_list | add_manga_to_list |
| get_my_manga_list | update_anime_progress |
| get_currently_watching | update_manga_progress |
| search_anime | update_anime_status |
| search_manga | update_anime_score |
| get_anime_details | update_manga_score |
| get_manga_details | update_list_entry |
| get_my_anime_statistics | remove_list_entry |
| | bulk_update_entries |

`update_list_entry` also handles manga status, volume progress, repeat count, priority, privacy and notes. It sends only the fields explicitly requested. Add refuses an existing entry. Update/delete verify the authenticated owner's existing entry and media ID.

Examples:

- “Find the different Fullmetal Alchemist versions before adding one.”
- “Add this verified anime ID to planning.”
- “Set my anime progress to five episodes.”
- “Set this manga to paused and show the updated entry.”
- “Read all pages of my library and ratings, then recommend five anime I haven't watched.”
- “Preview deleting this entry, including the score, progress and notes that would be removed.”

Recommendations are produced by your connected LLM using library, statistics and search results. The server does not call another model API or require a model-provider API key of its own.

### Changes and confirmation

Ordinary requested single-entry additions/updates execute directly. Set **dry_run: true** to validate and preview any write without executing it.

Deletion, bulk updates, progress reductions, dropping an entry, clearing an existing score, replacing existing notes and making a private entry public require a preview and confirmation:

1. The first tool call returns the exact preview and `confirmation_id`, with no write.
2. The agent shows it and asks you to confirm inside the harness.
3. After your confirmation it repeats the identical arguments with `confirmation_id` and `confirmed: true`.

The trusted harness/agent obtains the real human confirmation. The server validates the preview, ownership and current entry, expires previews after ten minutes and permits only one use. Configure the harness's tool approval controls as desired; write annotations are included. There is no browser confirmation page in local stdio mode.

### Input rules

- Status: CURRENT, PLANNING, COMPLETED, PAUSED, DROPPED, REPEATING.
- Use verified **AniList media IDs**, not MyAnimeList or list-entry IDs. Write selectors accept exactly one of media_id/title. Ambiguous titles return candidates for you to choose.
- Progress is an absolute episode/chapter count, never a delta. Manga volumes are separate. Known totals are checked.
- Scores use your profile's actual POINT_100, POINT_10_DECIMAL, POINT_10, POINT_5 or POINT_3 format. Zero clears a score; conversions are never guessed.
- Follow hasNextPage to fetch complete lists. Page size is at most 50; AniList's Page depth limit is 5000 entries. Narrow the status/search filter if needed and do not describe an incomplete fetch as the full library.
- Bulk updates support up to five existing entries with separate explicit patches. They are sequential, not atomic, and stop at the first failure with completed/failed/skipped results.
- A network failure may leave a write's result unknown. Read the affected entry before retrying. Mutations are never automatically retried. AniList may apply its own server-side save behavior.

## Tokens and security

Your token stays in the local server process and is sent only to AniList using an Authorization header. It is never returned as a tool result or written into generated host configuration. Do not paste tokens into conversations or command arguments.

Saved credentials live outside the repository:

- Windows: `%LOCALAPPDATA%\AniListManagerMCP\credentials.dpapi` (DPAPI CurrentUser).
- macOS/Linux: `~/.config/anilist-manager-mcp/credentials.secrets.json` (file 0600, directory 0700; not OS encryption).

ANILIST_ACCESS_TOKEN overrides the saved token. Set it using your harness's secret/environment UI rather than sharing a token-bearing config file. If that explicit token fails, the server never silently falls back to another account. Expired/revoked tokens return REAUTH_REQUIRED: replace the token using setup or the environment and reconnect the harness.

An AniList application client ID/client secret is different from an account access token. If you need to obtain a token through your own OAuth application instead of importing one, source-checkout commands `npm run setup:oauth` and `npm run auth` implement the authorization-code flow and loopback callback. AniList does not support refresh tokens.

Local stdio exposes no network listener. Access is controlled by your OS account and trusted harness. The optional [authenticated HTTP transport](docs/http.md) is separate and keeps its own OAuth and browser approval protections. This is a personal, single-account server.

Requests are serialized with at least 2.1 seconds between starts for AniList's documented temporary 30/minute rate limit, and Retry-After/reset headers are honored. Full-library reads can take time. Raw upstream errors, token-bearing headers and request payloads are never logged.

## Verification

```sh
# Installed release: real MCP process plus all nine read tools against your account
anilist-mcp smoke

# No token required: verify real MCP startup and discovery of all 19 tools
anilist-mcp smoke --discovery-only
```

Smoke checks never write to AniList and return a nonzero exit status on failure. They do not print actual account data or access tokens.

From a checkout:

```sh
npm run check
npm test
npm run test:package
npm run inspector
```

The suite blocks external requests and tests all tools, OAuth/HTTP protections, token import, vault storage, validation, confirmations and partial failures. A real stdio subprocess uses a test-only mocked AniList endpoint. The package check installs the actual release tarball in a clean directory with lifecycle scripts disabled, then verifies CLI/configuration and real MCP discovery. CI runs Node 22/24 on Windows, Linux and macOS.

Live public anime/manga searches and details have been checked successfully. Automated writes use mocks. Real personal-account reads and writes require each user's token; no live account mutations were made during development. Host setup commands follow official documentation; no claim is made that every LLM or harness version has been tested.

See [release maintenance](docs/releasing.md) for packaging and optional future npm publication. The project uses TypeScript, native fetch, Zod and the official `@modelcontextprotocol/sdk` 1.x package. License: MIT.