Pixiv MCP Server

一个功能强大的 Pixiv 工具集，通过模型上下文协议 (MCP) 为大语言模型（如 Claude）提供浏览、搜索和下载 Pixiv 内容的能力。

✨ 主要功能

🔍 多维度搜索

• 关键词搜索（search_illust）

• 用户搜索（search_user）

• 标签自动补全（search_autocomplete）

• 排行榜浏览（illust_ranking - 日榜/周榜/月榜等）

• 热门标签趋势（trending_tags_illust）

• 相关作品推荐（illust_related）

📥 智能下载

• 支持单个或批量作品下载（通过 download 工具）

• 异步后台下载，不阻塞 AI 操作

• 自动为多页作品（漫画）或动图创建独立子文件夹

• 动态检测 FFmpeg，自动将动图 (Ugoira) 转换为 GIF 格式

• 智能文件名清理，防止文件系统错误

• 支持随机推荐下载（download_random_from_recommendation）

👥 社区内容浏览

• 个人推荐内容（illust_recommended）

• 关注画师动态（illust_follow）

• 用户收藏夹浏览（user_bookmarks）

• 关注列表查看（user_following）

• 作品详细信息获取（illust_detail）

🔐 安全认证

• 使用官方推荐的 OAuth 2.0 (PKCE) 流程

• 提供 get_token.py 一次性认证向导脚本

• 自动生成和管理 .env 配置文件

• 🆕 智能 Token 管理：

  • 自动检测 token 失效并刷新

  • 手动刷新工具（refresh_token）

  • API 调用失败时自动重试机制

  • 详细的错误诊断和解决建议

🔧 环境要求

🚀 快速开始

📖 文档链接 / Documentation

中文文档:

• 中文说明文档

• 安装指南

• 快速开始

• DXT Token 配置指南 - DXT 专用 token 配置方法

English:

• Installation Guide

• DXT Extension README

步骤 1: 克隆或下载项目

步骤 2: 安装依赖 (推荐使用 uv)

本项目使用 pyproject.toml 管理依赖。推荐使用 uv 进行安装，它是一个极速的 Python 包管理器。

如果您仍希望使用 pip：

步骤 3: 获取认证 Token

运行认证向导：

重要提示：请严格按照终端提示操作。成功后会自动创建 .env 配置文件。

步骤 4: 启动与配置

完成安装后，项目已经注册为一个系统命令。

直接启动 (可选)

你可以在终端直接运行以下命令来启动服务器：

配置 MCP 客户端

在您的 MCP 客户端中，请使用以下配置。

配置说明：

• pixiv-server 可自定义为任意名称。

• command 使用 uv。

• args 中通过 --directory /path/to/your/pixiv-mcp-server 指定项目根目录的绝对路径（请务必替换为您的实际路径，例如 C:/Users/YourName/Documents/pixiv-mcp-server），然后 run pixiv-mcp-server 启动服务。

• env 部分为可选配置，未配置的环境变量将从 .env 文件读取。

✨ 主要功能与工具详解

🔍 多维度搜索

• search_illust(word, ...) - 根据关键词搜索插画，可选择是否包含 R-18 内容。

• search_user(word) - 搜索用户。

• trending_tags_illust() - 获取当前的热门标签趋势。

• illust_related(illust_id) - 获取与指定插画相关的推荐作品。

📥 智能下载

• download(illust_id, illust_ids) - 异步后台下载单个或多个作品。工具会自动判断类型并应用智能存储规则。动图(Ugoira)会自动转换为高质量GIF，并清理临时文件。

• download_random_from_recommendation(count) - 从用户的Pixiv推荐页随机下载N张插画。此为完成此类请求的最佳方式，会自动处理下载和动图转换。

• set_download_path(path) - 设置图片和动图的默认本地保存位置。路径不存在时会自动创建。

👥 社区内容浏览

• illust_recommended() - 获取官方推荐插画的文本列表。注意：此工具只返回作品信息，不执行下载。如需下载，请使用'download_random_from_recommendation'工具。

• illust_follow() - 获取已关注作者的最新作品（首页动态）(需要认证)。

• user_bookmarks(user_id) - 获取用户的收藏列表 (需要认证)。

• user_following(user_id) - 获取用户的关注列表 (需要认证)。

• illust_detail(illust_id) - 获取单张插画的详细信息。

• illust_ranking(mode) - 获取插画排行榜（日榜/周榜/月榜等）。

🔐 安全认证

• 使用官方推荐的 OAuth 2.0 (PKCE) 流程。

• 提供 get_token.py 一次性认证向导脚本。

• 自动生成和管理 .env 配置文件。

• 支持令牌刷新功能。

• 重要提示：服务器启动时会自动尝试使用环境变量中的 PIXIV_REFRESH_TOKEN 进行认证。无需手动调用认证工具。

🚀 最新更新与改进

• 🆕 智能 Token 自动刷新：新增自动检测 token 失效并刷新的机制，大幅提升 API 调用成功率和用户体验。

  • 自动检测认证错误并刷新 token

  • 新增 refresh_token 手动刷新工具

  • API 调用失败时自动重试机制

  • 详细的错误诊断和解决建议

  • 参见 TOKEN_REFRESH_GUIDE.md 获取详细说明

• 更稳定的 MCP 客户端配置：优化了启动配置，现在无需客户端支持 cwd 字段，通过 uv --directory 参数直接指定项目路径，兼容性更强。

• 动图（Ugoira）合成质量提升：修复了动图转换时可能出现的画面不完整或黑色块问题，现在生成的 GIF 质量更高。

• 下载任务反馈优化：修改了 download 工具的返回话术，明确提示动图合成可能需要时间，避免 AI 重复调用。

• 自动清理临时文件：修复了动图转换后遗留 .zip 压缩包的 Bug，现在会自动清理。

• 移除了冗余的 ：简化了工具集，避免 AI 在自动认证失败时误导性地向用户索要 Token。

• 全面优化工具描述：对所有工具的描述和返回话术进行了细致调整，提升 AI 对工具的理解和交互体验。

⚙️ 环境变量配置

文件命名模板变量

• {author} - 作者名称

• {title} - 作品标题

• {id} - 作品 ID

🔗 相关资源

• FastMCP: MCP 服务器框架

• pixivpy3: Pixiv API Python 库

• MCP 协议: 模型上下文协议文档

⚠️ 免责声明

本工具旨在便于用户通过现代 AI 工具访问个人 Pixiv 账号内容。使用时请：

• 遵守 Pixiv 用户协议

• 负责任地使用工具

• 尊重版权和创作者权益

开发者对任何账号相关问题不承担责任。所有操作均代表用户本人意愿。

🤖 AI 生成内容说明
本项目的代码和文档内容完全由人工智能生成。虽然经过了结构分析和功能测试，但仍可能存在不完善之处。使用前请仔细测试，如遇问题请及时反馈。

如有问题或建议，欢迎反馈交流。