222wcnm/pixiv-mcp-server

Pixiv MCP Server

A powerful Pixiv toolkit that empowers Large Language Models (like Claude / Cursor) to browse, search, and download content from Pixiv via the Model Context Protocol (MCP). Now featuring a brand-new card-based view for a more intuitive interactive experience.

✨ Key Features

🛠️ General Tools

• next_page(): Fetches the next page of results from the previous command.
• update_setting(key, value): Updates any server configuration at runtime (e.g., download_path).

📥 Download Management

• download(illust_id | illust_ids, ...): Asynchronously downloads specified artworks. Can accept optional parameters (webp_quality, gif_preset, etc.) to control ugoira conversion quality.
• manage_download_tasks(task_id, action): Manages download tasks. Supports status and cancel actions.

🔍 Search & Discovery

• search_illust(word, ...): Searches for illustrations by keyword.
• search_user(word, ...): Searches for users.
• get_illust_ranking(mode, ...): Retrieves the illustration rankings.
• get_illust_related(illust_id, ...): Gets recommended artworks related to the specified illustration.
• get_illust_recommended(...): Fetches a list of official recommended illustrations (Authentication required).
• get_trending_tags(): Gets the current trending tag trends.
• get_illust_detail(illust_id): Retrieves detailed information for a single illustration.

👥 Community & User

• get_follow_illusts(...): Fetches the latest works from followed artists (home feed) (Authentication required).
• get_user_bookmarks(user_id_to_check, ...): Retrieves a user's bookmark list (Authentication required).
• get_user_following(user_id_to_check, ...): Retrieves a user's following list (Authentication required).

⚙️ Output Views

To enhance the user experience in AI conversations, this toolkit introduces a view parameter to control the output format:

• view='cards' (Default): Displays results as rich Markdown cards with embedded image previews. This is the recommended mode for its intuitive and visually appealing presentation.
• view='raw': Returns the raw, unprocessed JSON data. This mode is suitable for programmatic use or when results need to be piped into other tools.

The default view is hardcoded as cards and cannot be changed via environment variables.

🔧 Requirements

🚀 Quick Start

Step 1: Clone or Download the Project

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

Step 2: Install Dependencies (uv recommended)

# Install uv (if not already installed)
pip install uv

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

Step 3: Obtain Authentication Token

Run the authentication wizard:

python get_token.py

A .env file containing PIXIV_REFRESH_TOKEN will be created or updated automatically upon success.

Step 4: Launch and Configure

In your MCP client, use the following configuration:

{
  "mcpServers": {
    "pixiv-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/pixiv-mcp-server",
        "run",
        "pixiv-mcp-server"
      ],
      "env": {
        "PIXIV_REFRESH_TOKEN": "Copy from .env file or leave empty to read automatically",
        "DOWNLOAD_PATH": "./downloads",
        "FILENAME_TEMPLATE": "{author} - {title}_{id}",
        "DEFAULT_LIMIT": "10",
        "UGOIRA_FORMAT": "webp"
      }
    }
  }
}

Please replace /path/to/your/pixiv-mcp-server with the absolute path to the project's root directory.

⚙️ Environment Variables

🔗 Related Resources

• FastMCP: MCP Server Framework
• pixivpy3: Pixiv API Python Library
• MCP Protocol: Model Context Protocol Documentation

⚠️ Disclaimer

This tool is intended to facilitate access to your personal Pixiv account content through modern AI tools. Please adhere to the Pixiv user agreement and respect copyright and creator rights. The developer assumes no responsibility for any account-related issues.

🤖 The code and documentation for this project were entirely generated by AI. While it has undergone structural analysis and functional testing, imperfections may still exist. Contributions via Issues/PRs to improve the experience are welcome.