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 调用失败时自动重试机制
  • 详细的错误诊断和解决建议

🔧 环境要求

组件	版本要求	说明
Python	3.10+	建议使用最新稳定版
FFmpeg	最新版	可选，用于 Ugoira 动图转 GIF
MCP 客户端	-	如 Claude for Desktop

🚀 快速开始

📖 文档链接 / Documentation

中文文档:

• 中文说明文档
• 安装指南
• 快速开始
• DXT Token 配置指南 - DXT 专用 token 配置方法

English:

• Installation Guide
• DXT Extension README

步骤 1: 克隆或下载项目

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

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

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

# 安装 uv (如果尚未安装)
pip install uv

# 创建虚拟环境并安装依赖
uv venv
uv pip install -e .

如果您仍希望使用 pip：

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

步骤 3: 获取认证 Token

运行认证向导：

python get_token.py

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

步骤 4: 启动与配置

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

直接启动 (可选)

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

pixiv-mcp-server

配置 MCP 客户端

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

{
  "mcpServers": {
    "pixiv-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/pixiv-mcp-server",
        "run",
        "pixiv-mcp-server"
      ],
      "env": {
        "PIXIV_REFRESH_TOKEN": "从.env文件复制或留空自动读取",
        "DOWNLOAD_PATH": "./downloads",
        "FILENAME_TEMPLATE": "{author}_{id}_{title}"
      }
    }
  }
}

配置说明：

• 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，现在会自动清理。
• 移除了冗余的 auth 工具：简化了工具集，避免 AI 在自动认证失败时误导性地向用户索要 Token。
• 全面优化工具描述：对所有工具的描述和返回话术进行了细致调整，提升 AI 对工具的理解和交互体验。

⚙️ 环境变量配置

变量名	必需	描述	默认值
PIXIV_REFRESH_TOKEN	✅	Pixiv API 认证令牌	无
DOWNLOAD_PATH	❌	下载文件根目录	./downloads
FILENAME_TEMPLATE	❌	文件命名模板	{author} - {title}_{id}
https_proxy	❌	代理服务器地址	无

文件命名模板变量

• {author} - 作者名称
• {title} - 作品标题
• {id} - 作品 ID

🔗 相关资源

• FastMCP: MCP 服务器框架
• pixivpy3: Pixiv API Python 库
• MCP 协议: 模型上下文协议文档

⚠️ 免责声明

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

• 遵守 Pixiv 用户协议
• 负责任地使用工具
• 尊重版权和创作者权益

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

---

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

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