### Smithery Example Configuration

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/configuration.md

An example of how to provide the MyAnimeList API client ID and secret in the Smithery configuration.

```yaml
exampleConfig:
  malClientId: your_client_id_here
  malClientSecret: your_client_secret_here
```

--------------------------------

### Manual Installation Configuration for Claude Desktop

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/README.md

Add this configuration to your `claude_desktop_config.json` file for manual installation. Ensure the `<path to your project>` is correctly set.

```json
{
    "mcpServers": {
        "myanimelist": {
            "command": "uv",
            "args": [
                "--directory",
                "<path to your project>",
                "run",
                "main.py"
            ]
        }
    }
}
```

--------------------------------

### Get Anime Details Response Example

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Example JSON response containing detailed information about a specific anime.

```json
{
  "id": 16498,
  "title": "Shingeki no Kyojin",
  "main_picture": { "medium": "...", "large": "..." },
  "synopsis": "...",
  "mean": 8.56,
  "genres": [{"id": 1, "name": "Action"}],
  "studios": [{"id": 1, "name": "WIT STUDIO"}],
  "num_episodes": 25,
  "status": "finished_airing"
}
```

--------------------------------

### Get User Anime List Response Example

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Example JSON response for a user's anime list, showing watched status and score.

```json
{
  "data": [
    {
      "node": {"id": 16498, "title": "Shingeki no Kyojin"},
      "list_status": {"score": 9, "num_watched_episodes": 25, "status": "completed"}
    }
  ]
}
```

--------------------------------

### Install MyAnimeList MCP Server via Smithery

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/README.md

Use this command to automatically install the MyAnimeList MCP Server for Claude Desktop using Smithery.

```bash
npx -y @smithery/cli install @nicoaguerrero/myanimelist-mcp-server --client claude
```

--------------------------------

### Environment Variables Example

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/configuration.md

Example of a .env file for storing MyAnimeList API credentials. These variables are automatically loaded by python-dotenv.

```env
MAL_CLIENT_ID=your_client_id_here
MAL_CLIENT_SECRET=your_client_secret_here
```

--------------------------------

### Search Anime Response Example

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Example JSON response for a successful anime search query.

```json
{
  "data": [
    {
      "node": {
        "id": 16498,
        "title": "Shingeki no Kyojin",
        "main_picture": { "medium": "...", "large": "..." }
      },
      "ranking": { "rank": 1, "type": "all" }
    }
  ],
  "paging": { "last_page": true }
}
```

--------------------------------

### Authentication Functions

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/COMPLETION-REPORT.txt

Documentation for the 6 authentication functions, including OAuth2 flows, token management, and credential setup. Detailed explanations and code examples are provided.

```APIDOC
## Authentication

This section covers the authentication mechanisms and functions.

### OAuth2 Authentication

- **Endpoint**: `/authentication`
- **Description**: Handles OAuth2 authorization code flow and token exchange.
- **Details**: See `api-reference/authentication.md` for detailed steps, parameters, and response formats.

### Token Management

- **Description**: Functions for refreshing and caching access tokens.
- **Details**: Covered within `api-reference/authentication.md` and `api-reference/user-tools.md`.
```

--------------------------------

### Smithery Start Command Configuration

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/configuration.md

Configures the MCP server to start as a Python process using stdio transport. It specifies the command and arguments, and injects environment variables from the configuration.

```yaml
startCommand:
  type: stdio
  commandFunction: |
    (config) => ({
      command: 'python',
      args: ['main.py'],
      env: {
        MAL_CLIENT_ID: config.malClientId,
        MAL_CLIENT_SECRET: config.malClientSecret
      }
    })
```

--------------------------------

### Pagination Example

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Illustrates how to paginate through results using the `offset` and `limit` parameters. Each call retrieves a specific slice of the data.

```APIDOC
## Pagination

### Description
Demonstrates how to paginate through results using `limit` and `offset`.

### Method
`get_anime_ranking(ranking_type: AnimeRanking, limit: int, offset: int)`

### Parameters
- **ranking_type** (AnimeRanking enum) - Required - The type of ranking.
- **limit** (integer) - Required - The number of items per page.
- **offset** (integer) - Required - The starting index for the results.

### Code Example
```python
# Get first page
page1 = await get_anime_ranking(AnimeRanking.ALL, limit=10, offset=0)

# Get second page
page2 = await get_anime_ranking(AnimeRanking.ALL, limit=10, offset=10)

# Get third page
page3 = await get_anime_ranking(AnimeRanking.ALL, limit=10, offset=20)
```
```

--------------------------------

### Get Recommendations

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Get anime recommendations for the authenticated user. This operation requires OAuth2 authorization.

```APIDOC
## Get Recommendations

### Description
Retrieves anime recommendations for the authenticated user.

### Authentication
Requires OAuth2 authorization.

### Method
`get_suggested_anime(limit: int)`

### Parameters
- **limit** (integer) - Optional - The maximum number of recommendations to return.
```

--------------------------------

### Initialize and Run FastMCP Server

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/README.md

Initializes the FastMCP server, registers all available tools, and starts the server using the stdio transport. This is the main entry point for the server.

```python
from mcp.server.fastmcp import FastMCP
from tools.tools import register_tools

mcp = FastMCP("myanimelist")
register_tools(mcp)

if __name__ == "__main__":
    mcp.run(transport="stdio")
```

--------------------------------

### Error Handling Example

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Demonstrates how to check for and handle API errors in the response. Errors are typically indicated by an 'error' key in the result dictionary.

```APIDOC
## Error Handling

### Description
Example of how to check for and process API errors.

### Code Example
```python
result = await get_anime(q="test")

if "error" in result:
    status = result.get("status_code", "unknown")
    error = result["error"]
    print(f"API Error {status}: {error}")
else:
    # Process result
    for anime in result.get("data", []):
        print(anime["node"]["title"])
```
```

--------------------------------

### Get Suggested Anime

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/user-tools.md

Fetches anime recommendations for the authenticated user. Specify the limit and offset for pagination. Requires a Bearer token for authentication.

```python
async def get_suggested_anime(limit: int = 10, offset: int = 0) -> dict:
```

```python
# Get recommendations for authenticated user
suggestions = await get_suggested_anime(limit=20, offset=0)
# Returns: {"data": [{"node": {"id": 1234, "title": "Recommended Anime"}}, ...]}}
```

--------------------------------

### Handling HTTP Status Errors

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/errors.md

This example demonstrates how to check for specific HTTP status codes in the error response, such as 404 (Not Found), and provides a general fallback for other API errors.

```python
result = await get_anime(q="Invalid")
if "error" in result and result.get("status_code") == 404:
    print("Anime not found")
elif "error" in result:
    print(f"API Error: {result['error']}")
```

--------------------------------

### Anime Tools

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/README.md

Functions for searching anime, fetching details, retrieving rankings, and getting seasonal anime information.

```APIDOC
## Anime Tools

### `get_anime(q, limit, offset)`

**Description:** Search anime.

### `get_anime_details(anime_id, fields)`

**Description:** Fetch detailed anime info.

### `get_anime_ranking(ranking_type, limit, offset)`

**Description:** Get anime rankings.

### `get_seasonal_anime(season, year, sort, limit, offset)`

**Description:** Get seasonal anime.
```

--------------------------------

### User Profile Response Example

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

A successful response (200 OK) for the user profile endpoint includes details like user ID, name, gender, birthday, location, join date, and optionally anime statistics.

```json
{
  "id": 12345,
  "name": "username",
  "gender": "Male",
  "birthday": "1990-01-01",
  "location": "USA",
  "joined_at": "2020-01-01T00:00:00+00:00",
  "anime_statistics": {
    "num_items": 100,
    "num_completed": 50,
    "num_watching": 10
  }
}
```

--------------------------------

### Common Field Queries

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Shows how to request specific fields when getting anime details, such as score, ranking, recommendations, and related works. You can also request all available fields.

```APIDOC
## Common Field Queries

### Description
Examples of requesting specific fields for detailed anime information.

### Method
`get_anime_details(anime_id: int, fields: list[str])`

### Parameters
- **anime_id** (integer) - Required - The ID of the anime.
- **fields** (list of strings) - Required - A list of fields to retrieve.

### Code Examples
```python
# Get anime score and ranking
await get_anime_details(anime_id=16498, fields=["mean", "rank"])

# Get recommendations
await get_anime_details(anime_id=16498, fields=["recommendations"])

# Get related works
await get_anime_details(anime_id=16498, fields=["related_anime", "related_manga"])

# Get everything
await get_anime_details(
    anime_id=16498,
    fields=["synopsis", "mean", "genres", "studios", "recommendations"]
)
```
```

--------------------------------

### API Endpoints Overview

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/COMPLETION-REPORT.txt

This section provides an overview of the documented API endpoints. For detailed information on each endpoint, including parameters, request/response examples, and error handling, please refer to the specific documentation files.

```APIDOC
## API Endpoints

This document outlines the available API endpoints for interacting with the myanimelist-mcp-server.

### Endpoints

- **Anime Tools**: Documentation for anime-related functions.
- **Manga Tools**: Documentation for manga-related functions.
- **User Tools**: Documentation for user and authentication functions.
- **Authentication**: Documentation for OAuth2 and token management.

Refer to the respective `.md` files in the `api-reference/` directory for detailed specifications of each endpoint.
```

--------------------------------

### Get Anime Ranking

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/anime-tools.md

Fetch anime rankings by type with pagination. Specify ranking type, limit, and offset. Max limit is 500.

```python
async def get_anime_ranking(ranking_type: AnimeRanking = AnimeRanking.ALL, limit: int = 10, offset: int = 0) -> dict:
```

```python
# Get top 10 highest-rated anime
rankings = await get_anime_ranking(AnimeRanking.ALL, limit=10, offset=0)
```

```python
# Get most popular anime
rankings = await get_anime_ranking(AnimeRanking.BYPOPULARITY, limit=50)
```

```python
# Get currently airing anime
rankings = await get_anime_ranking(AnimeRanking.AIRING, limit=20)
```

--------------------------------

### MCP Tool Functions

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/COMPLETION-REPORT.txt

Documentation for the 16 MCP tool functions, covering anime, manga, and user-related operations. Each function is documented with its signature, parameters, return types, error conditions, and code examples.

```APIDOC
## MCP Tools

This section details the 16 MCP tool functions available in the system.

### Anime Tools

- **Endpoint**: `/anime-tools`
- **Description**: Functions for interacting with anime data.
- **Details**: See `api-reference/anime-tools.md` for specific functions, parameters, and examples.

### Manga Tools

- **Endpoint**: `/manga-tools`
- **Description**: Functions for interacting with manga data.
- **Details**: See `api-reference/manga-tools.md` for specific functions, parameters, and examples.

### User Tools

- **Endpoint**: `/user-tools`
- **Description**: Functions for user management and authentication.
- **Details**: See `api-reference/user-tools.md` for specific functions, parameters, and examples.
```

--------------------------------

### Get Anime and Manga Details

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Retrieve detailed information for a specific anime or manga by its ID. You can specify which fields to include in the response.

```python
# Get detailed anime info
result = await get_anime_details(
    anime_id=16498,
    fields=["synopsis", "genres", "studios", "mean", "num_episodes"]
)
```

```python
# Get manga details
result = await get_manga_details(
    manga_id=13,
    fields=["synopsis", "authors", "num_chapters"]
)
```

--------------------------------

### get_suggested_anime

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/INDEX.md

Get anime recommendations for the authenticated user. Requires OAuth2 authentication.

```APIDOC
## get_suggested_anime

### Description
Get anime recommendations.

### Method
GET

### Endpoint
/recommendations/anime

### Authentication
OAuth2 required.
```

--------------------------------

### Get User Profile

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/user-tools.md

Fetches the authenticated user's profile information. Optionally include anime viewing statistics by setting the 'fields' parameter. Requires a Bearer token for authentication.

```python
async def get_user_profile(fields: Optional[str] = None) -> dict:
```

```python
# Get basic user profile
profile = await get_user_profile()
# Returns: {"id": 123, "name": "username", "joined_at": "2020-01-01T00:00:00+00:00"}
```

```python
# Get profile with anime statistics
profile = await get_user_profile(fields="anime_statistics")
# Includes: {"anime_statistics": {"num_items": 100, "num_completed": 50, ...}}
```

--------------------------------

### Get Anime Suggestions

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Retrieves a list of anime suggestions based on the user's current anime list. Requires OAuth2 authentication.

```APIDOC
## GET /v2/anime/suggestions

### Description
Fetches anime suggestions tailored to the user's viewing habits and list.

### Method
GET

### Endpoint
https://api.myanimelist.net/v2/anime/suggestions

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Results limit (1-100, default 10)
- **offset** (integer) - Optional - Pagination offset (default 0)

#### Header Parameters
- **Authorization** (string) - Required - Bearer {access_token}

### Response
#### Success Response (200 OK)
- List of recommended anime based on user's list.
```

--------------------------------

### Get Anime Ranking Endpoint

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Fetch a list of anime based on different ranking types. The ranking_type parameter is mandatory.

```http
GET https://api.myanimelist.net/v2/anime/ranking/{ranking_type}
```

--------------------------------

### API Request Call Graph

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/MODULE-GRAPH.md

Details the process for making API requests, including authentication, client setup, and response handling.

```python
Tool function (e.g., get_anime)
├── [if requires auth] get_mal_access_token() → Bearer token
├── os.getenv("MAL_CLIENT_ID") → API key
├── httpx.AsyncClient()
│   ├── GET/PUT/DELETE https://api.myanimelist.net/v2/...
│   ├── headers: {"X-MAL-CLIENT-ID": client_id} or {"Authorization": f"Bearer {token}"}
│   └── response.raise_for_status()
├── response.json() → dict
└── [on error] catch and return {"error": ...}
```

--------------------------------

### Get User Profile

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Retrieve the authenticated user's profile information. You can optionally request specific fields like `anime_statistics`.

```APIDOC
## Get User Profile

### Description
Retrieves the profile information for the authenticated user.

### Authentication
Requires OAuth2 authorization.

### Method
`get_user_profile(fields: str)`

### Parameters
- **fields** (string) - Optional - Specifies additional fields to retrieve (e.g., `"anime_statistics"`).
```

--------------------------------

### capture_authorization_code

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/authentication.md

Starts a local HTTP server to capture the OAuth2 authorization code from a callback. It validates the state parameter to prevent CSRF attacks and returns the authorization code received.

```APIDOC
## capture_authorization_code

### Description
Starts a local HTTP server and waits for the OAuth2 authorization code. This function is crucial for the OAuth2 authorization code flow, capturing the code returned by the authorization server after user consent.

### Method
Asynchronous Function

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **expected_state** (str) - Required - State value from `get_authorization_url()` for CSRF validation

### Returns
- **str** — Authorization code from callback.

### Errors
- `ValueError` — HTTP server failed to start, authorization code not received, or state mismatch

### Example
```python
url, verifier, state = await get_authorization_url()
webbrowser.open(url)
code = await capture_authorization_code(state)
```
```

--------------------------------

### Retry API Calls with Exponential Backoff

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/errors.md

Implement a retry mechanism for API calls that might fail due to rate limiting (HTTP 429). This example retries up to 3 times with increasing delays (1s, 2s, 4s).

```python
import asyncio

for attempt in range(3):
    result = await get_anime_ranking(AnimeRanking.ALL)
    if "error" not in result:
        return result
    if result.get("status_code") == 429:
        await asyncio.sleep(2 ** attempt)  # 1s, 2s, 4s
    else:
        break
```

--------------------------------

### Get User Anime and Manga Lists

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Fetch a user's anime or manga list based on their username and status (e.g., completed, watching). Supports sorting for anime lists.

```python
# Get user's completed anime
completed = await get_anime_list(
    username="tanjiro",
    status=AnimeStatus.COMPLETED,
    limit=20
)
```

```python
# Get user's watching anime
watching = await get_anime_list(
    username="tanjiro",
    status=AnimeStatus.WATCHING,
    sort=AnimeStatusSort.LIST_SCORE
)
```

```python
# Get user's manga list
manga = await get_manga_list(
    username="ichigo",
    status=MangaStatus.COMPLETED
)
```

--------------------------------

### HTTP Request Handler for OAuth2 Callback

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/authentication.md

Handles GET requests to the OAuth2 callback endpoint. Parses query parameters and sets module-level globals for the authorization code and state. Responds with an HTML confirmation.

```python
class CallbackHandler(http.server.SimpleHTTPRequestHandler):
    def do_GET(self):

```

--------------------------------

### Seasonal Anime

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Get a list of anime for a specific season and year using `get_seasonal_anime`. You can sort the results by score and limit the number of entries.

```APIDOC
## Seasonal Anime

### Description
Retrieves a list of anime airing in a specific season and year.

### Method
`get_seasonal_anime(season: Season, year: int, sort: SeasonSort, limit: int)`

### Parameters
- **season** (Season enum) - Required - The season (e.g., `Season.WINTER`).
- **year** (integer) - Required - The year of the season.
- **sort** (SeasonSort enum) - Optional - The sorting criteria (e.g., `SeasonSort.SCORE`).
- **limit** (integer) - Optional - The maximum number of results to return.
```

--------------------------------

### Get Seasonal Anime Endpoint

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Retrieve a list of anime airing in a specific year and season. Requires year and season path parameters.

```http
GET https://api.myanimelist.net/v2/anime/season/{year}/{season}
```

--------------------------------

### Get User Anime List

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Retrieves a user's anime list, allowing filtering by status and sorting. Supports pagination and requires an API client ID.

```APIDOC
## GET /v2/users/{username}/animelist

### Description
Retrieves a user's anime list, allowing filtering by status and sorting. Supports pagination and requires an API client ID.

### Method
GET

### Endpoint
https://api.myanimelist.net/v2/users/{username}/animelist

### Parameters
#### Path Parameters
- **username** (string) - Required - MyAnimeList username
#### Query Parameters
- **status** (string) - Optional - Status: watching, completed, on_hold, dropped, plan_to_watch
- **sort** (string) - Optional - Sort order: list_score, list_updated_at, anime_title, anime_start_date
- **limit** (integer) - Optional - Results limit (1-500, default 10)
- **offset** (integer) - Optional - Pagination offset (default 0)
#### Header Parameters
- **X-MAL-CLIENT-ID** (string) - Required - API client ID

### Response
#### Success Response (200)
- **data** (array) - List of anime in the user's list with their status.

### Response Example
```json
{
  "data": [
    {
      "node": {"id": 16498, "title": "Shingeki no Kyojin"},
      "list_status": {"score": 9, "num_watched_episodes": 25, "status": "completed"}
    }
  ]
}
```
```

--------------------------------

### Get Anime Details Endpoint

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Retrieve detailed information for a specific anime using its ID. The 'fields' parameter allows specifying which details to include.

```http
GET https://api.myanimelist.net/v2/anime/{anime_id}
```

--------------------------------

### Capture Authorization Code

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/authentication.md

Starts a local HTTP server to capture the authorization code from the OAuth2 callback. Validates the state parameter to prevent CSRF attacks. Requires the expected state value from the authorization URL.

```python
async def capture_authorization_code(expected_state: str) -> str:

```

```python
url, verifier, state = await get_authorization_url()
webbrowser.open(url)
code = await capture_authorization_code(state)

```

--------------------------------

### Get Anime Details

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Retrieves detailed information for a specific anime using its ID. Supports specifying fields to include and requires an API client ID.

```APIDOC
## GET /v2/anime/{anime_id}

### Description
Retrieves detailed information for a specific anime using its ID. Supports specifying fields to include and requires an API client ID.

### Method
GET

### Endpoint
https://api.myanimelist.net/v2/anime/{anime_id}

### Parameters
#### Path Parameters
- **anime_id** (integer) - Required - Anime ID
#### Query Parameters
- **fields** (string) - Optional - Comma-separated fields to include
#### Header Parameters
- **X-MAL-CLIENT-ID** (string) - Required - API client ID

### Response
#### Success Response (200)
- **id** (integer) - Anime ID.
- **title** (string) - Anime title.
- **main_picture** (object) - Main picture URLs.
- **synopsis** (string) - Anime synopsis.
- **mean** (number) - Average score.
- **genres** (array) - List of genres.
- **studios** (array) - List of studios.
- **num_episodes** (integer) - Number of episodes.
- **status** (string) - Current status of the anime.

### Response Example
```json
{
  "id": 16498,
  "title": "Shingeki no Kyojin",
  "main_picture": { "medium": "...", "large": "..." },
  "synopsis": "...",
  "mean": 8.56,
  "genres": [{"id": 1, "name": "Action"}],
  "studios": [{"id": 1, "name": "WIT STUDIO"}],
  "num_episodes": 25,
  "status": "finished_airing"
}
```
```

--------------------------------

### Get Anime and Manga Rankings

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Fetch ranked lists of anime and manga. Supports various ranking types like overall, by popularity, and by specific formats or genres.

```python
# Get top anime overall
top = await get_anime_ranking(AnimeRanking.ALL, limit=10)
```

```python
# Get most popular anime
popular = await get_anime_ranking(AnimeRanking.BYPOPULARITY, limit=20)
```

```python
# Get airing anime
airing = await get_anime_ranking(AnimeRanking.AIRING, limit=15)
```

```python
# Get top manga
top_manga = await get_manga_ranking(MangaRanking.ALL, limit=20)
```

```python
# Get light novels
novels = await get_manga_ranking(MangaRanking.NOVEL, limit=10)
```

--------------------------------

### Get User Anime List by Status

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/anime-tools.md

Fetches a user's anime list filtered by status and optionally sorted. Supports pagination with limit and offset parameters. Handles HTTP and network errors.

```python
async def get_anime_list(username: str, status: AnimeStatus, sort: Optional[AnimeStatusSort] = None, limit: int = 10, offset: int = 0) -> dict:
```

```python
# Get user's completed anime
completed = await get_anime_list("tanjiro", AnimeStatus.COMPLETED, limit=20)

# Get user's watching anime sorted by score
watching = await get_anime_list("nezuko", AnimeStatus.WATCHING, sort=AnimeStatusSort.LIST_SCORE)
```

--------------------------------

### Build Docker Image for MyAnimeList MCP Server

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/README.md

Build a Docker image for the MyAnimeList MCP server. Ensure you have the necessary MAL credentials for running the container.

```bash
docker build -t myanimelist-mcp .
```

--------------------------------

### Run MyAnimeList MCP Server with Docker

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/README.md

Run the MyAnimeList MCP server using a Docker container. Set the MAL_CLIENT_ID and MAL_CLIENT_SECRET environment variables.

```bash
docker run -e MAL_CLIENT_ID=... -e MAL_CLIENT_SECRET=... myanimelist-mcp
```

--------------------------------

### Get Authenticated User Operations

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Perform operations requiring OAuth2 authorization, such as getting user recommendations or profile information. You can request specific fields for the profile.

```python
# Get recommendations for authenticated user
suggestions = await get_suggested_anime(limit=10)
```

```python
# Get user's profile
profile = await get_user_profile()
```

```python
# Get profile with stats
profile = await get_user_profile(fields="anime_statistics")
```

--------------------------------

### Get MAL Access Token

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/authentication.md

Get the current or refreshed OAuth2 access token with caching. This function handles the entire OAuth2 flow, including silent refresh and browser-based authorization if necessary. It returns a valid OAuth2 bearer token.

```python
async def get_mal_access_token() -> str:
    # Function body not provided in source
```

```python
# First call: Opens browser for authorization
token = await get_mal_access_token()

# Subsequent calls: Returns cached token if still valid
token = await get_mal_access_token()  # Returns immediately

# Token expiring soon: Silently refreshes
# (happens if called >1 hour after first call)
token = await get_mal_access_token()  # Refreshes and returns new token
```

--------------------------------

### get_seasonal_anime

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/INDEX.md

Get anime airing in a specific season. This is a public tool.

```APIDOC
## get_seasonal_anime

### Description
Get seasonal anime.

### Method
GET

### Endpoint
/seasons/{year}/{season}

### Parameters
#### Path Parameters
- **year** (integer) - Required - The year of the season.
- **season** (Season) - Required - The season (winter, spring, summer, fall).

#### Query Parameters
- **sort** (SeasonSort) - Optional - The sorting criteria for the seasonal anime (e.g., score, num_list_users).
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The offset for pagination.
```

--------------------------------

### Implement Pagination

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Retrieve data in pages by using the 'limit' and 'offset' parameters. Each subsequent request increments the offset by the limit to fetch the next set of results.

```python
# Get first page
page1 = await get_anime_ranking(AnimeRanking.ALL, limit=10, offset=0)
```

```python
# Get second page
page2 = await get_anime_ranking(AnimeRanking.ALL, limit=10, offset=10)
```

```python
# Get third page
page3 = await get_anime_ranking(AnimeRanking.ALL, limit=10, offset=20)
```

--------------------------------

### Get User Profile

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Retrieves the profile information for the authenticated user. This endpoint requires OAuth2 authentication.

```APIDOC
## GET https://api.myanimelist.net/v2/users/@me

### Description
Retrieves the profile information for the authenticated user.

### Method
GET

### Endpoint
https://api.myanimelist.net/v2/users/@me

### Parameters
#### Query Parameters
- **fields** (string) - Optional - anime_statistics

#### Headers
- **Authorization** (string) - Required - Bearer {access_token}

### Response
#### Success Response (200 OK)
- **id** (integer) - The user's unique identifier.
- **name** (string) - The user's username.
- **gender** (string) - The user's gender.
- **birthday** (string) - The user's birthday in YYYY-MM-DD format.
- **location** (string) - The user's location.
- **joined_at** (string) - The date and time the user joined, in ISO 8601 format.
- **anime_statistics** (object) - An object containing the user's anime statistics.
  - **num_items** (integer) - Total number of anime items tracked.
  - **num_completed** (integer) - Number of completed anime.
  - **num_watching** (integer) - Number of anime currently being watched.

### Response Example
```json
{
  "id": 12345,
  "name": "username",
  "gender": "Male",
  "birthday": "1990-01-01",
  "location": "USA",
  "joined_at": "2020-01-01T00:00:00+00:00",
  "anime_statistics": {
    "num_items": 100,
    "num_completed": 50,
    "num_watching": 10
  }
}
```
```

--------------------------------

### Pagination Parameters

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/00-START-HERE.md

List endpoints utilize limit and offset for pagination. 'limit' specifies results per page, and 'offset' skips a specified number of results.

```python
limit=10        # Results per page
offset=0        # Skip N results
```

--------------------------------

### get_mal_access_token

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/authentication.md

Gets the current or a refreshed OAuth2 access token for MyAnimeList, with built-in caching and silent refresh capabilities.

```APIDOC
## get_mal_access_token

### Description
Get current or refreshed OAuth2 access token with caching.

### Method
GET (inferred from context of retrieving a token)

### Endpoint
/oauth2/token (inferred from context of token retrieval)

### Parameters
No parameters required.

### Response
#### Success Response (200)
- **access_token** (str) - Valid OAuth2 bearer token.

### Request Example
```python
token = await get_mal_access_token()
```

### Response Example
```json
{
  "access_token": "your_valid_oauth2_bearer_token"
}
```

### Behavior
1. If cached token exists and expires in >60 seconds, return it immediately
2. If refresh token exists, refresh the access token silently
3. Otherwise, trigger full OAuth2 flow: open browser, wait for code, exchange for tokens
4. Cache tokens globally and return access token

### Errors
- `httpx.HTTPStatusError` — Network errors during token refresh or exchange
- `ValueError` — Authorization code not received, state mismatch
```

--------------------------------

### get_manga

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/manga-tools.md

Searches for manga by a given query string, with support for pagination to control the number of results and the starting offset.

```APIDOC
## get_manga

### Description
Search for manga by query with pagination support.

### Method
```python
async def get_manga(q: str, limit: int = 10, offset: int = 0) -> dict:
```

### Parameters
#### Path Parameters
- **q** (str) - Required - Search query for manga title or keywords
- **limit** (int) - Optional - Number of results to return (max 100), defaults to 10
- **offset** (int) - Optional - Pagination offset for results, defaults to 0

### Response
#### Success Response (dict)
JSON response from MyAnimeList API containing matching manga list.

### Request Example
```python
result = await get_manga(q="One Piece", limit=5, offset=0)
# Returns: {"data": [{"node": {"id": 13, "title": "One Piece"}}, ...]}}
```
```

--------------------------------

### Main Python Module Imports

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/MODULE-GRAPH.md

Shows the import structure for the main Python script, highlighting dependencies like FastMCP, pydantic, and dotenv.

```text
main.py
├── mcp.server.fastmcp → FastMCP
└── tools.tools → register_tools()
    ├── httpx
    ├── typing → Optional, List, Annotated
    ├── pydantic → Field, ValidationError
    ├── mcp.server.fastmcp → FastMCP
    ├── utils.schemas → *, [AnimeRanking, Season, SeasonSort, AnimeStatus, AnimeStatusSort, MangaRanking, MangaStatus, MangaStatusSort]
    ├── dotenv → load_dotenv
    ├── os
    └── utils.auth → get_mal_access_token()
        ├── httpx
        ├── time
        ├── secrets
        ├── webbrowser
        ├── http.server, socketserver
        ├── urllib.parse
        ├── os
        ├── typing → Optional, Dict
        └── dotenv → load_dotenv

utils.schemas
└── enum → Enum
```

--------------------------------

### Get Seasonal Anime

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/QUICKSTART.md

Retrieve anime titles airing in a specific season and year, with options for sorting and limiting results.

```python
# Get anime from a season
result = await get_seasonal_anime(
    season=Season.WINTER,
    year=2024,
    sort=SeasonSort.SCORE,
    limit=20
)
```

--------------------------------

### Source Code Structure

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/README.md

This outlines the directory structure of the myanimelist-mcp-server project, indicating the purpose of key files and directories.

```tree
myanimelist-mcp-server/
├── main.py                      # Entry point
├── tools/
│   └── tools.py                # 16 MCP tools
├── utils/
│   ├── auth.py                 # OAuth2 & token management
│   └── schemas.py              # Type enums
├── pyproject.toml              # Python dependencies
├── smithery.yaml               # Smithery registry config
├── Dockerfile                  # Docker configuration
├── .env.example                # Environment template
└── README.md                   # Usage guide
```

--------------------------------

### OAuth2 Integration Data Flow for Authenticated Tools

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/MODULE-GRAPH.md

Details the process for handling user authentication when an authenticated tool is called. It includes checking cached tokens, using refresh tokens, and the steps involved in triggering and completing the OAuth2 flow if tokens are invalid.

```text
User calls authenticated tool
├── Check cached _access_token
├── If expired, use _refresh_token
├── If invalid, trigger OAuth2:
│   ├── Generate authorization URL
│   ├── Open in browser
│   ├── Wait for callback code
│   └── Exchange code for tokens
└── Cache and return token
```

--------------------------------

### Authentication Flow Call Graph

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/MODULE-GRAPH.md

Illustrates the function call sequence for authentication, including token caching, refresh, and the full OAuth2 flow.

```text
Tool requiring auth (e.g., update_myanimelist)
└── get_mal_access_token()
    ├── [if token cached and valid] → return _access_token
    ├── [if refresh token valid] → refresh_access_token()
    │   └── exchange_code_for_token (via MyAnimeList API)
    └── [otherwise] full OAuth2 flow:
        ├── get_authorization_url()
        │   └── get_new_code_verifier()
        ├── webbrowser.open(auth_url)
        ├── capture_authorization_code(state)
        │   └── socketserver.TCPServer + CallbackHandler
        └── exchange_code_for_token(code, verifier)
            └── MyAnimeList OAuth2 endpoint
```

--------------------------------

### Public Tools

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/MODULE-GRAPH.md

These tools can be called directly without requiring authentication. They provide access to various MyAnimeList data such as anime and manga information, rankings, and seasonal lists.

```APIDOC
## Public Tools

### Description
Access MyAnimeList data without authentication.

### Tools
- **get_anime(q, limit, offset)**: Search for anime.
- **get_anime_details(anime_id, fields)**: Get details for a specific anime.
- **get_anime_ranking(ranking_type, limit, offset)**: Retrieve anime rankings.
- **get_seasonal_anime(season, year, sort, limit, offset)**: Get anime for a specific season.
- **get_anime_list(username, status, sort, limit, offset)**: Get a user's anime list.
- **get_manga(q, limit, offset)**: Search for manga.
- **get_manga_details(manga_id, fields)**: Get details for a specific manga.
- **get_manga_ranking(ranking_type, limit, offset)**: Retrieve manga rankings.
- **get_manga_list(username, status, sort, limit, offset)**: Get a user's manga list.
```

--------------------------------

### MyAnimeList API Tool Data Flow

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/MODULE-GRAPH.md

Illustrates the sequence of operations for the MCP Tool when interacting with the MyAnimeList API. It covers parameter formatting, request building, sending requests via httpx, API interaction, and response parsing.

```text
MCP Tool
├── Format parameters
├── Build request (GET/PUT/DELETE)
├── Send via httpx.AsyncClient
├── MyAnimeList API (https://api.myanimelist.net/v2)
├── Parse JSON response
└── Return dict (or error dict)
```

--------------------------------

### Get Manga Ranking

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Fetches a ranked list of manga based on a specified ranking type. Supports pagination and requires an API client ID.

```APIDOC
## GET https://api.myanimelist.net/v2/manga/ranking/{ranking_type}

### Description
Fetches a ranked list of manga based on a specified ranking type. Supports pagination and requires an API client ID.

### Method
GET

### Endpoint
https://api.myanimelist.net/v2/manga/ranking/{ranking_type}

### Parameters
#### Path Parameters
- **ranking_type** (string) - Required - Type: all, manga, novels, oneshot, doujin, manhwa, manhua, bypopularity, favorite
#### Query Parameters
- **limit** (integer) - Optional - Results limit (1-500, default 100)
- **offset** (integer) - Optional - Pagination offset (default 0)
#### Header Parameters
- **X-MAL-CLIENT-ID** (string) - Required - API client ID

### Response
#### Success Response (200 OK)
Ranked manga list.
```

--------------------------------

### Type Enums

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/COMPLETION-REPORT.txt

Documentation for the 9 type enums used within the system, detailing their members, values, and usage.

```APIDOC
## Type Definitions

This section describes the various type enums used throughout the API.

### Enums

- **Count**: 9 documented enums.
- **Details**: See `types.md` for a complete list of enums, their members, values, and usage examples.
```

--------------------------------

### User Tools (Requires OAuth2 Authentication)

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/README.md

Functions for managing user-specific data, including anime and manga lists, profile information, and list item modifications.

```APIDOC
## User Tools (Requires OAuth2 Authentication)

### `get_anime_list(username, status, sort, limit, offset)`

**Description:** Get user's anime list.

### `get_suggested_anime(limit, offset)`

**Description:** Get recommendations.

### `get_user_profile(fields)`

**Description:** Get authenticated user's profile.

### `delete_myanimelist_item(anime_id)`

**Description:** Remove anime from list.

### `delete_mymangalist_item(manga_id)`

**Description:** Remove manga from list.

### `update_myanimelist(anime_id, status, score, ...)`

**Description:** Update anime list entry.

### `update_mymangalist(manga_id, status, score, ...)`

**Description:** Update manga list entry.
```

--------------------------------

### Get Seasonal Anime

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Retrieves a list of anime airing in a specific year and season. Supports sorting, pagination, and requires an API client ID.

```APIDOC
## GET /v2/anime/season/{year}/{season}

### Description
Retrieves a list of anime airing in a specific year and season. Supports sorting, pagination, and requires an API client ID.

### Method
GET

### Endpoint
https://api.myanimelist.net/v2/anime/season/{year}/{season}

### Parameters
#### Path Parameters
- **year** (integer) - Required - Year (e.g., 2024)
- **season** (string) - Required - Season: winter, spring, summer, fall
#### Query Parameters
- **sort** (string) - Optional - Sort order: anime_score, anime_num_list_users
- **limit** (integer) - Optional - Results limit (1-500, default 10)
- **offset** (integer) - Optional - Pagination offset (default 0)
#### Header Parameters
- **X-MAL-CLIENT-ID** (string) - Required - API client ID

### Response
#### Success Response (200)
- List of anime from the specified season.
```

--------------------------------

### Get Anime Ranking

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Retrieves a list of ranked anime based on the specified ranking type. Supports pagination and requires an API client ID.

```APIDOC
## GET /v2/anime/ranking/{ranking_type}

### Description
Retrieves a list of ranked anime based on the specified ranking type. Supports pagination and requires an API client ID.

### Method
GET

### Endpoint
https://api.myanimelist.net/v2/anime/ranking/{ranking_type}

### Parameters
#### Path Parameters
- **ranking_type** (string) - Required - Type: all, airing, upcoming, tv, ova, movie, special, bypopularity, favorite
#### Query Parameters
- **limit** (integer) - Optional - Results limit (1-500, default 10)
- **offset** (integer) - Optional - Pagination offset (default 0)
#### Header Parameters
- **X-MAL-CLIENT-ID** (string) - Required - API client ID

### Response
#### Success Response (200)
- List of ranked anime with rank position.
```

--------------------------------

### get_user_profile

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/user-tools.md

Fetches the authenticated user's profile information. Optionally includes anime viewing statistics.

```APIDOC
## get_user_profile

### Description
Fetch the authenticated user's profile information.

### Method
Asynchronous Python function call

### Parameters
#### Query Parameters
- **fields** (Optional[str]) - Optional - Default: None - Set to "anime_statistics" to include anime viewing stats

### Request Example
```python
# Get basic user profile
profile = await get_user_profile()

# Get profile with anime statistics
profile = await get_user_profile(fields="anime_statistics")
```

### Response
#### Success Response
- **id** (int) - User's unique identifier.
- **name** (str) - User's username.
- **joined_at** (str) - The date and time the user joined.
- **anime_statistics** (dict) - Optional - User's anime viewing statistics (if requested).

### Response Example
```json
{
  "id": 123,
  "name": "username",
  "joined_at": "2020-01-01T00:00:00+00:00"
}
```

```json
{
  "id": 123,
  "name": "username",
  "joined_at": "2020-01-01T00:00:00+00:00",
  "anime_statistics": {
    "num_items": 100,
    "num_completed": 50
  }
}
```
```

--------------------------------

### Get Manga Details

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/endpoints.md

Retrieves detailed information for a specific manga using its ID. Supports requesting specific fields and requires an API client ID.

```APIDOC
## GET https://api.myanimelist.net/v2/manga/{manga_id}

### Description
Retrieves detailed information for a specific manga using its ID. Supports requesting specific fields and requires an API client ID.

### Method
GET

### Endpoint
https://api.myanimelist.net/v2/manga/{manga_id}

### Parameters
#### Path Parameters
- **manga_id** (integer) - Required - Manga ID
#### Query Parameters
- **fields** (string) - Optional - Comma-separated fields to include
#### Header Parameters
- **X-MAL-CLIENT-ID** (string) - Required - API client ID

### Response
#### Success Response (200 OK)
Manga details with requested fields.
```

--------------------------------

### Generate MyAnimeList OAuth2 Authorization URL

Source: https://github.com/nicoaguerrero/myanimelist-mcp-server/blob/master/_autodocs/api-reference/authentication.md

Creates the MyAnimeList OAuth2 authorization URL, along with a PKCE code verifier and a state parameter for CSRF protection. The user is redirected to this URL to grant access.

```python
async def get_authorization_url() -> tuple[str, str, str]:
    # User authorizes and is redirected to http://localhost:8080/callback?code=...&state=...
    url, verifier, state = await get_authorization_url()
    print(f"Open this URL: {url}")
```