playbooks

home / mcp / pixiv mcp server

Pixiv MCP Server

Provides a Pixiv MCP Server to query, browse, and download Pixiv content via MCP, with token-based authentication and background downloads.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "amxkifir-pixiv-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/pixiv-mcp-server",
        "run",
        "pixiv-mcp-server"
      ],
      "env": {
        "DOWNLOAD_PATH": "./downloads",
        "FILENAME_TEMPLATE": "{author}_{id}_{title}",
        "PIXIV_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
      }
    }
  }
}

You can run a Pixiv MCP Server that lets your large language model browse, search, and download Pixiv content through the Model Context Protocol (MCP). It streamlines searching illustrations, following artists, managing downloads, and token-based authentication, all without blocking AI workflows.

How to use

Use a compatible MCP client to connect to the Pixiv MCP Server. You can perform keyword searches, search by user, get autocomplete suggestions for tags, browse rankings, view trending tags, and see related illustrations. For downloads, request single or batch downloads in the background; the server will organize multi-page works into dedicated folders, convert Ugoira animations to GIFs when FFmpeg is available, and clean up temporary files. You can also inspect detailed information about specific illustrations and view content from followed authors and user bookmarks.

Key tools you will typically use include: - search_illust: search illustrations by keywords - search_user: search for a Pixiv user - illust_ranking: browse daily, weekly, or monthly rankings - illust_related: find illustrations related to a given one - illust_detail: retrieve detailed information for a specific illustration - download: asynchronously download one or more illustrations - download_random_from_recommendation: download random illustrations from a user's recommendations - illust_recommended / illust_follow / user_bookmarks / user_following: browse recommended content and activity from followed authors - get_token / refresh_token: manage authentication tokens - set_download_path: configure the default local save location All of these operate through MCP client commands or UI integrations, enabling seamless AI-driven workflows without manual file handling.

How to install

# Step 1: Install prerequisites
Python 3.10+
FFmpeg (optional for Ugoira to GIF)
uv (Python package manager)

# Step 2: Clone the project
git clone https://github.com/amxkifir/pixiv-mcp-server.git
cd pixiv-mcp-server

# Step 3: Install dependencies
# Using uv for fast dependency management
pip install uv
uv venv
uv pip install -e .

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

# Step 4: Obtain authentication token
python get_token.py

Configuration and security

The server uses OAuth 2.0 with PKCE for secure authentication. A one-time setup script helps you obtain tokens and generate a local .env file. Token refreshing is automatic and a manual refresh tool is provided for rare cases of token expiry. The server will retry API calls on failure and provide detailed error diagnostics to help you resolve issues quickly.

Environment variables you will configure include:
- PIXIV_REFRESH_TOKEN: Pixiv API authentication token (required)
- DOWNLOAD_PATH: local directory for saves (default: ./downloads)
- FILENAME_TEMPLATE: how files are named (default: {author}_{title}_{id})
These variables are loaded from the .env file or environment when you start the server.
{
  "mcpServers": {
    "pixiv_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/pixiv-mcp-server",
        "run",
        "pixiv-mcp-server"
      ],
      "env": {
        "PIXIV_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",
        "DOWNLOAD_PATH": "./downloads",
        "FILENAME_TEMPLATE": "{author}_{id}_{title}"
      }
    }
  }
}

Notes and troubleshooting

The server creates a background task system for downloads so AI prompts remain responsive. If you enable FFmpeg, Ugoira animations are converted to high-quality GIFs and temporary archives are automatically cleaned up after processing. Ensure your ABSOLUTE path in the startup command matches your environment when starting the server from an MCP client.

Available tools

search_illust

Search illustrations by keywords with optional content filters.

search_user

Search Pixiv users by name or keyword.

search_autocomplete

Provide tag autocomplete suggestions for building queries.

illust_ranking

Retrieve illustration rankings (daily/weekly/monthly).

trending_tags_illust

Fetch currently popular tags for illustrations.

illust_related

Find illustrations related to a specified artwork.

download

Asynchronously download one or more illustrations and manage storage.

download_random_from_recommendation

Download a random set of illustrations from a user’s recommendations.

set_download_path

Define the default local download directory.

illust_recommended

List official recommended illustrations (no automatic download).

illust_follow

Get latest works from followed artists (requires authentication).

user_bookmarks

Retrieve a user’s bookmarks (requires authentication).

user_following

Get the list of followed users (requires authentication).

illust_detail

Fetch detailed information for a single illustration.