mcp-animenewsnetwork

# mcp-animenewsnetwork

[![npm](https://img.shields.io/npm/v/mcp-animenewsnetwork.svg)](https://www.npmjs.com/package/mcp-animenewsnetwork)
[![CI](https://github.com/smeet666/mcp-animenewsnetwork/actions/workflows/ci.yml/badge.svg)](https://github.com/smeet666/mcp-animenewsnetwork/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/mcp-animenewsnetwork.svg)](./LICENSE)

An [MCP](https://modelcontextprotocol.io) server for
[Anime News Network](https://www.animenewsnetwork.com). Search the anime and manga
encyclopedia, read cast, staff and episode lists, and follow the news wire.
**No API key, no account, no configuration.**

_(Version française plus bas / [French version below](#mcp-animenewsnetwork-français))_

---

## Quickstart

**One-click install**

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=animenewsnetwork&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1hbmltZW5ld3NuZXR3b3JrIl19)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=animenewsnetwork&config=%7B%22name%22%3A%22animenewsnetwork%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-animenewsnetwork%22%5D%7D)

**Claude Code**

```bash
claude mcp add animenewsnetwork -- npx -y mcp-animenewsnetwork
```

**Claude Desktop, Cursor, and any client using the standard config format**

```json
{
  "mcpServers": {
    "animenewsnetwork": {
      "command": "npx",
      "args": ["-y", "mcp-animenewsnetwork"]
    }
  }
}
```

**Bundle, without npm**

Download `mcp-animenewsnetwork-<version>.mcpb` from
[the latest release](https://github.com/smeet666/mcp-animenewsnetwork/releases/latest) and open
it. A client that supports MCP bundles installs it on its own, with no npm and
no configuration file to edit. The bundle carries its dependencies, so nothing
is fetched at install time.

## Tools

| Tool            | What it does                                              | Key parameters                                  |
| --------------- | --------------------------------------------------------- | ----------------------------------------------- |
| `search_titles` | Finds anime and manga by title. Compact rows only.        | `query`, `kind`, `limit`                        |
| `get_title`     | Reads one entry, section by section.                      | `id`, `kind`, `sections`, `max_chars`, `offset` |
| `list_recent`   | Lists recent additions, or browses titles alphabetically. | `kind`, `starts_with`, `limit`, `offset`        |
| `get_news`      | Reads the news, reviews and combined feeds.               | `feed`, `edition`, `category`, `limit`          |

Search returns an encyclopedia `id` and a `kind` for every result; `get_title`
takes both. That is the intended chain: search, then read.

The server is **read-only**. It writes nothing back to Anime News Network.

### Things worth knowing

**Search results carry no records.** A name search on the encyclopedia returns
the complete record of every match. A search for "One Piece" is 1.4 MB of XML,
roughly 360,000 tokens, because 47 full records are embedded in it. This server
reduces the same search to about 10 KB of rows. Read the entry you actually
want with `get_title`.

**One entry is still large, so sections are opt-in.** A record for a
long-running series reaches 79 KB: Cowboy Bebop alone carries 101 cast credits,
70 staff credits, 54 releases and 207 linked news items. `get_title` returns
`basic` by default, and `cast`, `staff`, `episodes`, `releases`, `related`,
`news` and `reviews` only when you ask.

**A trimmed cast keeps every language.** Credits arrive ordered alphabetically
by language, so taking the first sixty answers "who voices this character" with
whichever dub sorts first and can miss the Japanese cast entirely. Each language
keeps a share of the budget instead, and `cast_languages` reports the full count
per language, so a trimmed list still shows what exists. A `lang` of `null`
means the site recorded none, and says nothing about whether a credit is the
original.

**Search matches titles, and nothing else.** It cannot find a series from a
character, a studio, a genre or a plot detail. There is no full-text search
endpoint on the encyclopedia, and the `search` parameter their reports accept
returns nothing. Narrow the query rather than raising `limit`.

**A failure is never an empty result.** Anime News Network answers every
request with HTTP 200, including its failures, which it reports as a `<warning>`
inside the body. An unknown id would otherwise read as "this series does not
exist", so this server turns those warnings into errors with a code.

**The news feed is the whole archive.** There is no endpoint reaching further
back than the feed window, so older coverage cannot be retrieved here.

## Configuration

Every variable is optional. Set them in the `env` block of your MCP client config.

| Variable                | Default                                    | Purpose                                                         |
| ----------------------- | ------------------------------------------ | --------------------------------------------------------------- |
| `ANN_USER_AGENT`        | `mcp-animenewsnetwork v<version> (<repo>)` | User-Agent sent to Anime News Network.                          |
| `ANN_MIN_INTERVAL_MS`   | `1100`                                     | Minimum gap between requests. Values below 1000 ms are ignored. |
| `ANN_TIMEOUT_MS`        | `15000`                                    | Per-request timeout.                                            |
| `ANN_MAX_RETRIES`       | `3`                                        | Retries on rate limiting and transient errors.                  |
| `ANN_CACHE_TTL_MS`      | `3600000`                                  | Encyclopedia cache lifetime (1 hour).                           |
| `ANN_NEWS_CACHE_TTL_MS` | `300000`                                   | News cache lifetime (5 minutes).                                |
| `ANN_CACHE_MAX_ENTRIES` | `200`                                      | In-memory cache size, shared shape across both caches.          |
| `ANN_LOG_LEVEL`         | `error`                                    | `silent`, `error`, `info` or `debug`. Logs go to stderr.        |

The interval floor exists because Anime News Network documents a limit of one
request per second per IP and **delays** anything above it rather than refusing,
so pacing faster only queues requests on their side.

## How it works

The encyclopedia is a real public XML API, so this server makes plain HTTP calls
to `https://cdn.animenewsnetwork.com/encyclopedia` and maps the responses. The
news comes from the RSS feeds on the main site. It sends one request at a time,
paces itself, backs off when rate limited, and keeps two in-memory caches: an
hour for the encyclopedia, which barely changes, and five minutes for the wire,
which publishes several times an hour.

### On robots.txt

`animenewsnetwork.com/robots.txt` disallows `/encyclopedia/api.xml`, under a
comment reading "disallowed for search engines because redundant". This server
uses that endpoint anyway, and the reasoning is worth stating so you can judge
it yourself.

Anime News Network documents `api.xml` as a public API, publishes a rate limit
for it, asks callers to identify themselves and to attribute the data, and
advises caching responses for a week. Those are the instructions of a service
that expects clients, not one asking to be left alone. robots.txt governs
crawlers building an index; this server issues one request in response to one
question from one person, holds the answer briefly, and indexes nothing.

The server honours all of it: one request per second, an identifying
User-Agent, caching, and a source link on every result. If Anime News Network
would rather it did not exist, opening an issue is enough.

## Development

```bash
npm install
npm run build:fixtures   # regenerate the XML test fixtures
npm test                 # unit tests, no network
npm run typecheck
npm run build
ANN_LIVE=1 npm run test:live   # hits the real API, excluded from CI
npm run inspector        # explore the tools in the MCP Inspector
```

Fixtures are generated, not captured: they reproduce Anime News Network's
element names and attributes with placeholder titles, so the tests are
deterministic and no third-party content lives in this repository.

The API layer (`src/ann`) does not import the MCP SDK and is published
separately as `mcp-animenewsnetwork/client`, so it can be used as a plain
library.

## Data and attribution

The encyclopedia and the news wire are the work of Anime News Network and its
contributors. This project claims no rights over them and ships none of their
content.

Anime News Network asks that anything built on their data names them as the
source and links the entry it quotes. Every result this server returns carries a
`source_url` or a `link` for that purpose. If you display or repeat what it
returns, keep that attribution and link back.

This is an unofficial project, with no affiliation to or endorsement by Anime
News Network.

## Contributing

Bugs, questions and ideas all belong in
[the issue tracker](https://github.com/smeet666/mcp-animenewsnetwork/issues). Pull requests
are welcome; please open an issue first so we can agree on what the right
answer is before you write it. [CONTRIBUTING.md](CONTRIBUTING.md) has the
detail, and [SECURITY.md](SECURITY.md) covers anything exploitable.

## Support

These servers are free and stay free. If one of them saved you an afternoon,
you can [buy me a coffee](https://buymeacoffee.com/smeet666).

## License

MIT. See [LICENSE](./LICENSE). The license covers this source code only, not the
data retrieved through it.

---

<a name="mcp-animenewsnetwork-français"></a>

# mcp-animenewsnetwork (franç