Pixiv CLI MCP Server

<div align="center">

pixiv-cli

Pixiv CLI · MCP server (stdio / HTTP)

English · 简体中文

<p><a href="https://github.com/FlanChanXwO/pixiv-cli/actions/workflows/ci.yml"><img alt="Quality gate" src="https://github.com/FlanChanXwO/pixiv-cli/actions/workflows/ci.yml/badge.svg?event=push"></a> <a href="https://github.com/FlanChanXwO/pixiv-cli/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/FlanChanXwO/pixiv-cli?style=flat-square"></a> <a href="go.mod"><img alt="Go" src="https://img.shields.io/github/go-mod/go-version/FlanChanXwO/pixiv-cli?style=flat-square"></a> <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/FlanChanXwO/pixiv-cli?style=flat-square"></a> <img alt="Views" src="https://hits.sh/github.com/FlanChanXwO/pixiv-cli.svg?style=flat-square&amp;label=views"></p>

Install · Quick start · Interfaces · Documentation · Contributing

</div>

Unofficial CLI and MCP server for Pixiv: search, browse, bookmark, follow and download from a terminal or an AI agent. It also reads Pixiv Fanbox content (read-only).

Not affiliated with or endorsed by Pixiv Inc. Follow Pixiv's terms and applicable law.

flowchart LR
    U["You / scripts"] --> CLI["pixiv CLI"]
    A["AI agents"] --> MCP["pixiv mcp<br/>stdio · HTTP+OAuth"]
    CLI --> SDK["public Go SDK<br/>(account-bound API objects)"]
    MCP --> SDK
    SDK --> PX["Pixiv App API<br/>(authenticated only)"]
    SDK -.-> FB["Pixiv Fanbox<br/>(read-only, FANBOXSESSID)"]
    CLI -.->|"search IMAGE"| RS["SauceNAO · ascii2d"]
    MCP -.->|"reverse search"| RS

What you get

Area	Highlights
Discover	Search artworks/novels/users; filter by rating, subtype, AI mode, aspect ratio, resolution, drawing tool, bookmark count; all 16 ranking modes; recommendations, timelines, series, comments
Reverse search	Local image or URL → SauceNAO / ascii2d → canonical Pixiv records
Download	Artwork IDs/URLs, creator and public-bookmark URLs, allowed CDN URLs; page ranges, quality, GIF/APNG Ugoira; full success/warning/failure report
Account actions	Bookmarks, follows, comments and stamps
Accounts	Browser OAuth login, multi-account, token rotation, optional cross-machine relay, opt-in account pool honoring Retry-After
MCP	Same features as tools; image and Ugoira bytes; MCP Apps gallery over HTTP
Pipelines	Piped lists emit canonical NDJSON that detail, download, bookmark and follow consume
Pixiv Fanbox	Read-only creators, posts, feeds, tags and first-party files with a separate FANBOXSESSID

flowchart LR
    S["pixiv search miku"] -->|"NDJSON (auto when piped)"| D["pixiv detail"]
    S -->|NDJSON| DL["pixiv download"]
    R["pixiv ranking"] -->|NDJSON| B["pixiv bookmark add"]

Install

Channel	Command
Homebrew (macOS/Linux, recommended)	brew install FlanChanXwO/tap/pixiv-cli · upgrade: brew update && brew upgrade pixiv-cli
Script (Linux/macOS)	curl -fsSLo /tmp/pixiv-install.sh https://github.com/FlanChanXwO/pixiv-cli/releases/latest/download/install.sh && sh /tmp/pixiv-install.sh --add-to-path
Script (Windows cmd.exe, no PowerShell)	curl.exe -fsSLo "%TEMP%\pixiv-install.cmd" https://raw.githubusercontent.com/FlanChanXwO/pixiv-cli/main/scripts/install.cmd && call "%TEMP%\pixiv-install.cmd" --add-to-path
Docker (linux amd64/arm64)	docker pull ghcr.io/flanchanxwo/pixiv-cli:v1.2.3 (also docker.io/flanchanxwo/pixiv-cli)
Go	go install github.com/FlanChanXwO/pixiv-cli/cmd/pixiv@vX.Y.Z (exact tag)
Archive / source	GitHub Releases · sh scripts/build.sh (CGO_ENABLED=0, no Rust/C toolchain)

• Scripts detect AMD64/ARM64, verify the Release SHA-256, preflight the binary and install per-user. --no-path leaves PATH alone; --install-dir DIR changes the destination. Inspect the script before running it.
• Direct downloads ship checksums and an Ed25519-signed manifest. Details: installation, Docker, Go source.

<details> <summary>Install with an AI agent (copy this prompt)</summary>

Install the latest stable pixiv-cli from https://github.com/FlanChanXwO/pixiv-cli for this machine: inspect the repository's scripts/install.sh or scripts/install.cmd first, choose the script matching the detected OS and architecture (the Windows path must use cmd.exe and must not invoke PowerShell), download only official GitHub Release assets, require the published SHA-256 check to pass before replacing anything, install per-user without administrator or root privileges, add only the chosen install directory to the user PATH, ask before installing any missing prerequisite, never read or output Pixiv credentials, verify with pixiv --version, and report the installed version plus every file and PATH change.

Also install the `pixiv-cli` Skill that matches the same stable release tag (not main): download the full skills/pixiv-cli/ directory from that tag into the agent skills directory the user confirms. Do not guess the skills path and do not follow the main branch for skill content.

The published Skill is also on SkillHub and ClawHub (clawhub install pixiv-cli). Pin it to the version matching your CLI; pixiv <cmd> --help remains the final source of syntax.

</details>

60-second quick start

pixiv auth login                                   # browser OAuth, saved by UID
pixiv search "初音ミク" --content-type illust --ai-mode exclude --resolution high
pixiv search "初音ミク" --type novel --search-by tag-exact
pixiv search ./image.png --provider ascii2d-color --json    # reverse image search
pixiv detail https://www.pixiv.net/artworks/123456
pixiv download https://www.pixiv.net/artworks/123456 --pages 1,3-5 --quality regular
pixiv download https://www.pixiv.net/users/12345678/artworks          # whole creator
pixiv search "miku" --limit 20 | pixiv download                      # pipeline
pixiv bookmark add 123456 && pixiv follow add 12345678
pixiv recommended --type all --limit 10
pixiv timeline latest --type artwork --limit 20

pixiv fanbox auth import && pixiv fanbox post 123456       # FANBOX (hidden input)

pixiv --help and the CLI reference cover every command, flag, config key and environment variable.

Choose your interface

CLI

Text by default, --json for one document, --ndjson (or a pipe) for record streams.

pixiv ranking --mode day --json
pixiv user detail 12345678

MCP

flowchart LR
    Host["MCP host / agent"] -->|"stdio (default)"| L["pixiv mcp<br/>local CLI accounts"]
    Host -->|"HTTP + OAuth bearer"| H["pixiv mcp --port 1270<br/>remote / cloud connectors"]

Local (stdio) — add to your MCP client config:

{
  "mcpServers": {
    "pixiv": {
      "command": "pixiv",
      "args": ["mcp"]
    }
  }
}

Remote (authenticated HTTP):

pixiv mcp auth init                                        # once; prints the owner secret once
pixiv mcp --port 1270                                      # http://127.0.0.1:1270/mcp
pixiv mcp --port 1270 --base-url https://mcp.example.com   # behind an HTTPS reverse proxy

An authorized HTTP connector acts on the server's files and network (e.g. reverse search can read server-side paths), so grant access only to clients you trust. Tools, transports and setup details: MCP tools · HTTP startup.

Documentation

Guide	For
Installation	Channels, Docker, trust, pixiv update
Authentication	Login, remote hand-off, token import/export
CLI reference	Commands, flags, config, downloads, MCP startup
MCP tools · MCP Apps gallery	Tool schemas, output, HTTP authorization, Gallery UI
Go SDK	API objects, caller-owned credentials, reverse search and page downloads in Go
Architecture · MCP server	Package boundaries and runtime flow
Coding standards	Go conventions for contributors
Development · CI · Release	Toolchain, tests, PR gates, releases
Changelog	User-visible changes

Contributing

Bug reports, docs fixes, tests and focused features are welcome — read CONTRIBUTING.md first and discuss large or public-interface changes before coding.

Thank you to everyone who helps improve pixiv-cli.

<a href="https://github.com/FlanChanXwO/pixiv-cli/graphs/contributors"> <img src="https://contrib.rocks/image?repo=FlanChanXwO/pixiv-cli" alt="Contributors to pixiv-cli"> </a>

View all contributors

License

MIT © FlanChanXwO. Release archives contain only the executable.