pixiv

Pixiv MCP Server provides a feature-rich set of tools to browse, search, and download Pixiv content through the Model Context Protocol (MCP). It supports multi-dimensional search (search_illust, search_user, search_autocomplete, illust_ranking, trending_tags_illust, illust_related), smart downloading with asynchronous background tasks (download, download_random_from_recommendation), and community content browsing (illust_recommended, illust_follow, user_bookmarks, user_following, illust_detail, illust_ranking). Authentication uses the OAuth 2.0 PKCE flow, with a one-time get_token.py helper and automatic .env generation. The server can automatically refresh tokens and retry failed API calls, making it robust for long-running AI interactions. To use, install the server, obtain an access token, and configure the MCP client to run pixiv-server via uv, including your download path and a filename template. Once running, you can invoke tools like search_illust for keyword-driven discovery, download to fetch content asynchronously, and illust_ranking or trending_tags_illust to explore popular items.

In your MCP client, you will specify the server and command, along with environment variables such as PIXIV_REFRESH_TOKEN, DOWNLOAD_PATH, and FILENAME_TEMPLATE. The system handles token management automatically, and you can rely on tools like download_random_from_recommendation for curated content from Pixiv recommendations. The combination of search, browse, and download capabilities enables a seamless workflow for knowledge assistants and automation pipelines dealing with Pixiv content.

Prerequisites: Python 3.10+, a suitable package manager (uv recommended), and Git. You will also need to obtain a Pixiv refresh token via the provided get_token.py helper.

1. Clone the repository:

git clone https://github.com/amxkifir/pixiv-mcp-server.git
cd pixiv-mcp-server

2. Install dependencies with uv (recommended):

# Install uv if not present
pip install uv

# Create a virtual environment and install the project
uv venv
uv pip install -e .

If you prefer pip directly:

python -m venv .venv
source .venv/bin/activate  # Windows: .\.venv\Scripts\activate
pip install -e .

3. Obtain an authentication token:

python get_token.py

Follow the prompts to generate a .env file containing PIXIV_REFRESH_TOKEN and other defaults.4) Run the server via MCP client configuration (see mcp_config example) or start directly if the project exposes a console entry. The README example indicates using uv rather than a standalone Python script, with the directory pointing to your project and the command to run pixiv-mcp-server.

Tips and common considerations:

• Ensure PIXIV_REFRESH_TOKEN is set in the environment or in the generated .env file; this is required for authentication.
• The DOWNLOAD_PATH is optional; if omitted or missing, the server will use ./downloads by default. You can customize FILENAME_TEMPLATE to control how downloaded files are named.
• When running Ugoira (Pixiv animated images), the server can convert to GIF if FFmpeg is available on the system. Ensure FFmpeg is installed if you plan to convert.
• The MCP client configuration uses uv --directory to locate the project path and run pixiv-mcp-server; ensure the path you provide is absolute and correct.
• The server supports token auto-refresh and automatic retry on API failures; however, long-running tasks may still require periodic monitoring for failures in edge cases.
• If you run into token or network issues, check the .env file and ensure the refresh token is valid. Logs from the MCP server will guide troubleshooting.