AI导哈

插画搜索下载服务器

Pixiv MCP Server 是一个为 Pixiv 提供的模型上下文协议服务器，使大型语言模型能够直接搜索、浏览和下载插画。

  • by 222wcnm
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 222wcnm/pixiv-mcp-server

使用说明

Pixiv MCP服务器

Pixiv的模型上下文协议（MCP）服务器，使LLM能够直接搜索、浏览和下载插图。

✨ 主要特点

  • 搜索与发现：按关键字（标签/标题）、查看排名和趋势标签搜索插图和用户。
  • 详细信息和预览：使用本地代理获取详细的插图信息，以绕过Referer限制，允许LLM查看图像。
  • 下载管理：异步后台下载（自动将Ugoira转换为GIF/WebP），具有任务状态跟踪功能。
  • 个性化：访问用户书签、以下列表和官方推荐（需要身份验证）。
  • 结构化输出：所有工具都返回结构化JSON，并为客户端发布MCP输出模式。

🚀 快速开始

1.安装

需要Python 3.10+。使用安装依赖项 uv （推荐）或 pip:

uv sync

2.配置

复制 .env.example 到 .env （如果缺少则创建）并设置环境变量：

# Pixiv Refresh Token (required for Pixiv API tools)
# Recommended: run `uvx gppt login -j` and copy the JSON `refresh_token`
PIXIV_REFRESH_TOKEN=your_refresh_token_here

# (Optional) Download path, defaults to ./downloads
DOWNLOAD_PATH=./downloads

# (Optional) Proxy settings (Required in some regions)
HTTPS_PROXY=http://127.0.0.1:7890

HTTPS_PROXY 作为两者传递给PixivPy3 http 和 https 请求代理。预览图像代理在获取上游Pixiv图像时使用相同的代理URL。

获得Pixiv刷新令牌的推荐方法：

# Preferred: browser OAuth flow maintained by gppt
uvx gppt login -j

# If your network needs a proxy
HTTPS_PROXY=http://127.0.0.1:7890 uvx gppt login -j

# Fallback: built-in manual callback helper
uv run python get_token.py --env-file .env

内置助手写入 .env 旁边 get_token.py 默认情况下。如果写作 .env 如果失败，它将显示目标路径并在打印完整路径之前询问 PIXIV_REFRESH_TOKEN=... 用于手动保存的行。

3.跑步

# stdio mode (default, for Claude Desktop and local clients)
uv run pixiv-mcp-server

# SSE mode (Server-Sent Events)
uv run pixiv-mcp-server sse --host 0.0.0.0 --port 8000

# HTTP mode (Streamable HTTP, recommended for web deployment)
uv run pixiv-mcp-server http --host 0.0.0.0 --port 8000

# Debug with MCP Inspector
npx -y @modelcontextprotocol/inspector uv run pixiv-mcp-server

HTTP和SSE传输本身不添加身份验证。如果绑定到非本地主机，例如 0.0.0.0，将服务器置于经过身份验证的反向代理之后或限制网络访问。

4.MCP客户端配置

将以下内容添加到您的MCP客户端（例如，Claude Desktop）：

{
  "mcpServers": {
    "pixiv": {
      "command": "uv",
      "args": ["--directory", "/path/to/pixiv-mcp-server", "run", "pixiv-mcp-server"],
      "env": {
        "PIXIV_REFRESH_TOKEN": "your_token_here"
      }
    }
  }
}

替换 /path/to/pixiv-mcp-server 使用您的实际项目路径

🛠️ MCP工具

搜索

  • search_illust：搜索插图（支持R-18过滤器）
  • search_user：搜索用户
  • get_trending_tags：获取当前趋势标签

插画

  • get_illust_detail：获取插图详细信息
  • get_illust_ranking：获取排名（每日/每周/每月）
  • get_illust_related：获取相关/类似作品
  • get_illust_recommended：获取官方推荐（需要授权）

用户

  • get_user_bookmarks：获取用户书签（需要身份验证）
  • get_user_following：获取用户关注列表（需要身份验证）

下载

  • download：创建后台下载任务（批处理支持）
  • manage_download_tasks：查询或取消下载任务

工具集

  • next_page：从显式文件中获取下一页 cursor
  • update_setting：在运行时更新服务器配置

v3响应格式

所有MCP工具返回相同的信封：

{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {},
  "display_markdown": "optional markdown for clients"
}

结构化字段，如 cards, illust, tags, task_ids, tasks，以及 results 生活在...之下 data.计数、消息、分页和重启提示都在下面 metaMarkdown仅用于显示，不应被视为数据模型。

分页是无状态的。搜索/列表工具返回 meta.pagination.cursor 当另一个页面存在时：

{
  "meta": {
    "pagination": {
      "has_more": true,
      "cursor": "..."
    }
  }
}

将该值传递给 next_page(cursor) 继续。

v2到v3迁移

v2 v3
next_page() 使用了服务器端的先前命令状态 next_page(cursor) 用途 meta.pagination.cursor
cards, illust, tags, task_ids, tasks 位于顶层 已移至下方 data
markdown / summary 作为主要输出 display_markdown 是可选的显示文本
filtered_count, display_count，分页在顶层 移至下方 meta
update_setting 接受的宽密钥 只接受运行时安全密钥；代理、主机、端口和刷新令牌需要重新启动

📦 资源

  • pixiv://config：查看当前服务器配置
  • pixiv://tasks：查看当前下载任务队列

📝 提示

  • search_prompt：生成标准搜索说明
  • download_prompt：生成标准下载流程说明

📦 发布（维护人员）

版本控制：更新 [project].version 在 pyproject.toml 在上传之前。PyPI不允许为相同的项目名称、版本和分发类型重用分发文件名。 凭证：发布脚本使用 UV_PUBLISH_TOKEN 设置时；否则，它将读取匹配项 [pypi] 或 [testpypi] 令牌来自 $HOME\.pypirc.

# Build + test + sdist safety check + package metadata validation (no upload)
.\scripts\pypi_release.ps1

# Upload to TestPyPI
.\scripts\pypi_release.ps1 -TestPyPI -Upload

# Upload to PyPI
.\scripts\pypi_release.ps1 -Upload

⚠️ 免责声明

本项目仅用于教育和研究目的。Pixiv的所有图像版权均归其各自的作者所有。请勿将此项目用于非法抓取或商业目的。使用风险自负。

相关 MCP