A comprehensive Model Context Protocol (MCP) server for intelligent anime search and episode URL extraction from the AnimeWorld website.

This MCP server transforms the Kotlin CloudStream3 AnimeWorld plugin functionality into a robust, production-ready solution that provides:

• Intelligent Search: Fast API search with web scraping fallback
• Episode Extraction: Complete episode lists with metadata
• Streaming URL Extraction: Direct video URLs with VidGuard support
• Comprehensive Metadata: Detailed anime information and recommendations

• Fast API Search: Uses AnimeWorld's API endpoint for quick results
• Web Scraping Fallback: Comprehensive search results via web interface
• Dual Language Support: Italian dubbed and Japanese subtitled variants
• Pagination Support: Handles multiple pages of results
• Rich Metadata: Title, poster, type (Anime/OVA/Movie), dub status

• Complete Episode Lists: Extracts all episodes with metadata
• Server Information: Shows which streaming server each episode uses
• Episode Identification: Provides episode IDs and data for streaming extraction
• Metadata Extraction: Anime title, description, poster, and additional info

• Multiple Server Support: Handles various streaming sources
• VidGuard Integration: Decodes complex VidGuard URLs from listeamed.net
• JavaScript Decoding: Executes JavaScript to extract protected streaming links
• Direct URLs: Returns actual video streaming URLs ready for playback

• Comprehensive Details: Synopsis, genres, ratings, year, status
• External IDs: MyAnimeList and AniList integration
• Recommendations: Related anime suggestions
• Trailer Support: Extracts trailer URLs when available

• Python 3.11 or higher
• uv package manager

1. The server is self-contained and will automatically set up its environment
2. Use the provided run.sh script to start the server in STDIO mode
3. Configure your MCP client to use the server

# Search for anime by title
result = search_anime("Attack on Titan")
print(f"Found {result['total_results']} results")
for anime in result['results']:
    print(f"Title: {anime['title']}, Type: {anime['type']}, Dubbed: {anime['dubbed']}")

# Extract episodes from an anime page
episodes = get_episodes("https://www.animeworld.ac/view/vinland-saga.12345")
print(f"Found {episodes['total_episodes']} episodes")
for episode in episodes['episodes']:
    print(f"Episode {episode['number']}: {episode['title']}")

# Extract streaming URLs for a specific episode
streaming = get_streaming_urls("1¿https://www.animeworld.ac/view/vinland-saga.12345")
for url_info in streaming['streaming_urls']:
    print(f"Source: {url_info['source']}, URL: {url_info['url']}")

# Get comprehensive anime information
info = get_anime_info("https://www.animeworld.ac/view/vinland-saga.12345")
print(f"Title: {info['title']}")
print(f"Year: {info['year']}, Status: {info['status']}")
print(f"Genres: {', '.join(info['genres'])}")
print(f"Rating: {info['rating']}")

• Primary Search: /api/search/v2?keyword={query} for fast results
• Episode API: /api/episode/info?id={episode_id} for streaming URLs
• Fallback Scraping: Web interface parsing for comprehensive results

• Episode Lists: Parses .widget.servers > .widget-body .server .episode
• Anime Details: Extracts from .widget.info .info and .meta sections
• Pagination: Handles multiple pages with &page={page} parameter

• JavaScript Execution: Uses js2py for JavaScript code execution
• Signature Decoding: Implements complex URL signature decoding algorithm
• Base64 Processing: Handles obfuscated streaming URL generation

• Graceful Fallbacks: Multiple extraction methods with automatic fallbacks
• Timeout Management: Reasonable timeouts for all network operations
• Content Validation: Verifies extracted URLs and handles malformed responses

• Anime Series: Regular TV anime series
• Anime Movies: Feature-length anime films
• OVAs: Original Video Animations
• Dub Variants: Italian dubbed versions
• Sub Variants: Japanese subtitled versions

The server includes built-in rate limiting considerations:

• Respectful request patterns with appropriate delays
• Session management with proper cookie handling
• Error recovery mechanisms
• Timeout handling for long-running operations

No browser automation required - uses direct HTTP requests with proper headers and session management.

All tools return structured JSON responses with consistent formatting:

{
  "success": true,
  "data": { ... },
  "timestamp": 1234567890,
  "source": "api|web_scraping"
}

Error responses include:

{
  "error": "Error description",
  "timestamp": 1234567890
}

The server is designed to work out-of-the-box with no additional configuration required. All necessary session management, cookie handling, and API integration is handled internally.

animeworld-mcp/
├── src/animeworld_mcp/
│   ├── __init__.py
│   └── tools.py          # Core implementation
├── server.py             # FastMCP server
├── run.sh               # Startup script
├── mcp-server.json      # Configuration
├── README.md            # This file
└── examples/            # Usage examples

1. Extend AnimeWorldClient class in src/animeworld_mcp/tools.py
2. Add new tools using @mcp.tool decorator in server.py
3. Update documentation and examples

This MCP server is based on the CloudStream3 AnimeWorld plugin implementation. When contributing:

1. Ensure all new features maintain the same robust error handling
2. Test with both API and web scraping fallbacks
3. Verify VidGuard URL extraction works correctly
4. Update documentation for any new functionality

This project is based on the CloudStream3 AnimeWorld plugin and follows similar licensing terms.

• Based on the CloudStream3 AnimeWorld plugin
• Uses FastMCP framework for MCP implementation
• Implements VidGuard URL decoding algorithms from the original plugin