AniList-MCP 🚀

A production-grade Model Context Protocol (MCP) server for AniList, written in Node.js & TypeScript, reusing the proven anilist-node library.

Connects your AI agents (Claude Desktop, Cursor, Antigravity IDE, etc.) directly to AniList to discover anime schedules, query user profile stats, search titles, and retrieve recommendations.

✨ Features (Phase 1 MVP)

• 📺 Airing Schedules: Real-time broadcast schedules, countdown timers, and next-episode trackers.
• 👤 User Profile & Stats: In-depth statistics (episodes watched, minutes spent, chapters read, average scores, genres).
• 🔍 Search Anime & Manga: Fast title lookups with rich metadata (synonyms, romanized/English titles, cover images).
• 💡 Recommendations: Discover related works based on community ratings or fetch individual recommendation threads.
• 🔐 Flexible Auth: Works out-of-the-box for public queries; accepts ANILIST_TOKEN for authenticated/private data.
• 🐳 Docker-Ready with /health: Dual transport support (stdio for local tools, sse for remote containers) with an HTTP /health probe.

📋 Table of Contents

• Quick Start
• Configuration
• Client Integration
• MCP Tools Reference
• Docker Deployment
• Testing
• Documentation
• Author
• License

⚡ Quick Start

Option A: Run via Docker (Recommended)

# Clone the repository
git clone https://github.com/OldemarJesus/AniList-MCP.git
cd AniList-MCP

# Start with Docker Compose
docker compose up -d --build

# Verify health status
curl http://localhost:3000/health

Option B: Run Locally with Node.js

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in Stdio mode (Default)
npm start

# Or run in SSE/HTTP mode with /health endpoint
TRANSPORT=sse PORT=3000 npm start

⚙️ Configuration

AniList-MCP is configured via environment variables or a .env file:

🔌 Client Integration

1. Claude Desktop (claude_desktop_config.json)

Stdio Mode (Direct Node execution):

{
  "mcpServers": {
    "anilist": {
      "command": "node",
      "args": ["/absolute/path/to/AniList-MCP/dist/index.js"],
      "env": {
        "ANILIST_TOKEN": "your_optional_token"
      }
    }
  }
}

Docker Mode:

{
  "mcpServers": {
    "anilist": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "TRANSPORT=stdio", "anilist-mcp:latest"]
    }
  }
}

2. Cursor / Antigravity IDE (SSE Mode)

When running the Docker container with TRANSPORT=sse:

• URL: http://localhost:3000/sse

🛠️ MCP Tools Reference

See docs/api.md for full parameter schemas and response formats.

🩺 Health Check Endpoint

In sse mode, the server serves an HTTP /health endpoint:

curl http://localhost:3000/health

{
  "status": "ok",
  "service": "anilist-mcp",
  "version": "1.0.0",
  "uptime": 128.45,
  "transport": "sse",
  "authenticated": false,
  "timestamp": "2026-10-26T04:26:00.000Z"
}

🧪 Testing

AniList-MCP includes automated tests verifying tool execution, input schemas, and health checks:

# Run unit and integration tests
npm test

# Run tests in watch mode
npm run test:watch

📚 Documentation

Detailed documentation is available in the docs/ directory:

• PRD (Product Requirements Document)
• TL;DR Summary
• Agent Integration Guidelines
• System Architecture
• API Reference
• Docker Guide
• Developer Guide

👤 Author

Developed and maintained by Oldemar Jesus.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.