Skip to main content
Glama

media-hunter-mcp

搜索并下载 e621、rule34.xxx、E-Hentai / ExHentai、Pixiv 的作品。支持图片、视频、多图画廊及 Pixiv ugoira;提供 MCP 工具和独立命令行。

快速开始

在项目目录运行(Python 3.11+、uv):

uv sync --extra animation
uv run media-hunter check

animation 安装项目内使用的 ffmpeg,可将 ugoira 转成 GIF/MP4。已有系统 ffmpeg 时可仅运行 uv sync,或设置 ugoira_format = "zip" 保存原始动图包。

首次安装时复制 config.example.tomlconfig.toml,填写站点凭证。已有 config.toml 可继续使用。

Related MCP server: Pixiv MCP Server

配置

读取顺序:MEDIA_HUNTER_CONFIG 环境变量 → 当前目录 config.toml → 源码项目目录 config.toml~/.config/media-hunter/config.toml。命令行的 --config 优先于以上规则。相对下载目录以配置文件所在目录为基准。

配置

用途

download_root

下载根目录,支持 ~ 和相对路径

[network].proxy

HTTP(S)/SOCKS5 代理;空字符串表示直连,不读取系统代理环境变量

[network].timeout

单次 HTTP 网络操作的超时秒数

[network].retries

每个候选地址的最大尝试次数,1–10,包含首次请求

[sites.e621]

可选 usernameapi_key;可自定义描述性 user_agent

[sites.rule34]

必填 user_idapi_key,在站点账户 Options 页面生成

[sites.ehentai]

cookieuse_exhentai = true 时必须提供 Cookie

[sites.pixiv]

必填 refresh_token;支持 api_baseoauth_baseimage_mirror

每站可设置 request_intervaldownload_delaydownload_concurrency(1–16)。每次网络尝试都限速;download_delay 控制各文件开始处理的间隔,download_concurrency 控制同一作品内部的并发数。同一服务进程的不同下载调用会排队,排队时间计入总超时。

mirror_base 是用户自行配置的可信反向代理。e621/rule34 的 API 在连接失败、429 或可重试 5xx 后尝试镜像;E-Hentai 的镜像作为主地址。Pixiv 可分别设置 API/OAuth 主地址和图片镜像。API 镜像不会自动套用到图片 CDN 或 OAuth 地址。认证请求可能经配置的反向代理发送,请只使用自己信任的地址。

Pixiv 令牌在内存中自动续期。刷新返回的新 refresh token 会在当前服务进程内使用;重新启动仍读取配置中的值。配置文件不自动改写。

MCP 接入

以 OpenCode 为例,在其配置的 mcp 段添加:

"media-hunter": {
  "type": "local",
  "command": [
    "uv", "run", "--project",
    "C:/Projects/media-hunter-mcp",
    "--extra", "animation", "media-mcp"
  ],
  "enabled": true,
  "environment": {
    "MEDIA_HUNTER_CONFIG": "C:/Projects/media-hunter-mcp/config.toml"
  }
}

其他 MCP 客户端使用相同的命令、参数和环境变量,配置结构依客户端而定。默认使用 stdio,标准输出只传输 MCP 协议。更新项目后重新启动 MCP 客户端或其服务进程。

也支持 MEDIA_HUNTER_TRANSPORT=http(Streamable HTTP,默认 /mcp 路径)或 sse;默认监听 127.0.0.1:8787。可用 MEDIA_HUNTER_HOSTMEDIA_HUNTER_PORT 覆盖。HTTP 模式未配置身份验证,应在受信任的本机环境使用。

工具

工具

功能

search

站点原生标签/关键词搜索,支持 limitpagemin_scorerating

get_post

作品元数据;E-Hentai 的 ID 格式为 gid/token

download_post

下载整部作品或整本画廊,不受批量 50 文件上限限制

download_search

搜索并下载,整批最多尝试 50 个文件;超额画廊整本跳过

download_url

严格识别四站作品页面 URL 后下载,不接受任意文件直链

self_check

并行检查凭证与 API/首页连通性,每站最多 45 秒;不保证所有媒体链接可下载

搜索 page 从 1 开始。limit 上限:e621 320、rule34 1000、E-Hentai 100、Pixiv 30;批量下载的 limit 还限制为最多 50 个作品。E-Hentai 使用实际的 Next 游标顺序翻页,最多 100 页;深页查询比第一页慢。返回的是站点当前页中符合条件的结果,过滤后可能少于 limit。

rating 语义:e621 为 s/q/e 或完整名称;rule34 为 safe/questionable/explicit;Pixiv 为 all(不限)、safe、r18、r18g,后面三种精确匹配;E-Hentai 为画廊分类,例如 Manga、Non-H。min_score 对 Pixiv 表示收藏数,对 E-Hentai 表示星级。

下载工具的 timeout 是覆盖排队、搜索/详情、图片页解析、传输与合成的总秒数。省略表示不限制总时长;网络操作仍使用 [network].timeout

下载结果

  • 文件流式写入随机 .part 临时文件,完成且长度检查通过后原子替换目标文件。失败或取消会清理本次未完成文件。

  • 作品下的 JSON sidecar 保存元数据、文件清单和失败页;ugoira 的帧顺序和延时也会保存。

  • E-Hentai 每本画廊有独立目录,即使指定相同 subdir 也不会覆盖另一本的页码文件。

  • E-Hentai 图片页在每张实际下载前解析;单页失败会记录并继续其他页,认证或配额错误会停止尚未开始的请求。

  • 部分失败时返回 success: falseerror.type: partial_download,同时在 data 返回已完成文件及错误。批量下载还返回 skipped

  • 超时后已完成文件保留;取消中的作品清单写入 sidecar,批量结果的 total_files 统计已返回的作品结果,不包含取消中作品的残余完成文件。

  • 重试会重新请求作品文件;现有完整文件只在新下载成功后被替换。

目录布局:e621/rule34 按日期归档;Pixiv 按作者归档;E-Hentai 按画廊 ID 和标题归档。subdir 是清理后的分组名,不是任意路径。

命令行

uv run media-hunter check
uv run media-hunter search e621 "landscape" --rating safe --limit 5
uv run media-hunter search pixiv "風景" --rating safe --limit 5
uv run media-hunter get pixiv <作品ID>
uv run --extra animation media-hunter download-url "作品页面URL" --timeout 300
uv run media-hunter download-search e621 "landscape" --rating safe --limit 3 --timeout 180

指定配置:uv run media-hunter --config "配置文件路径" check。命令行输出 JSON;操作失败或部分完成退出码为 1,启动/配置失败为 2。

验证与维护

uv run --extra animation pytest -q
uv run ruff check src tests
uv run ruff format --check src tests

测试默认不联网,覆盖 OAuth 续期、站点解析、下载中断、取消清理、文件上限、画廊分页、真实 ffmpeg GIF/MP4 合成和真实 stdio MCP 子进程。手动联网检查:

uv run --extra animation python tests/live_smoke.py

联网检查会下载 e621/Pixiv 的 safe 小样、尝试 E-Hentai Non-H 小样;rule34 只检查搜索、详情与 CDN HEAD。报告和小样写入 .validation/,不写入日常下载根目录。

代码结构:server.py 仅处理 MCP 接入,cli.py 提供命令行;service.py 编排业务;sites/ 负责站点协议;network.py 管理请求;downloader.py 管理落盘与合成。新增站点时实现 SiteAdapter 并注册到 MediaService

许可证

本项目采用 MIT License

实际凭证只填写在本地 config.toml 中;该文件、部署资料、备份和验证产物均已加入 .gitignore。公开仓库仅提供凭证为空的 config.example.toml

Available Tools

6 tools
download_postA

按 ID 下载整部作品,返回文件清单及 sidecar。subdir 为下载根目录下的分组名。 timeout 为覆盖等待、元数据、解析、下载及合成的总秒数。失败文件不会成为最终文件。

ParametersJSON Schema
NameRequiredDescriptionDefault
siteYes
subdirNo
post_idYes
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden and does substantive work: it defines timeout as covering multiple phases, clarifies subdir semantics, and states that failed files will not become final files. It does not mention auth, overwrite behavior, or partial-file cleanup, but it gives meaningful operational detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences, front-loaded with the core action and returning value, followed by terse clarifications of the non-obvious parameters. Every sentence earns its place and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is largely complete for a download tool: it covers return contents, parameter semantics for the unusual fields, timeout scope, and failure behavior. The main gaps are undocumented site values and no explicit routing to sibling tools, but an output schema exists and the core call contract is clear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds real meaning for subdir and timeout, and post_id is implied by 'by ID', but the required site parameter is left entirely unexplained, leaving an agent to guess at valid values or the role of site in the request.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'download entire work by ID' and names the return value (file list and sidecar). This distinguishes it from siblings like download_url (by URL) and download_search (by search) without requiring the agent to open schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have a post ID and want a full download, but it never explicitly says when to prefer this over download_url or download_search, nor gives exclusions. Guidance is implicit rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

download_urlC

识别四个站点的作品页面 URL 并下载。timeout 为总秒数;不接受任意文件直链。

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
subdirNo
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It tells the caller that timeout is total seconds and that direct links are rejected, but it does not disclose whether the download creates files, requires authentication, has rate limits, or what side effects occur. This is a significant gap for a download tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the main purpose. However, it omits essential parameter semantics and behavioral details, making it under-specified rather than efficiently complete. It earns a 4 for brevity and structure, not for completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema (per context signals), which may compensate for return-value details. But given the tool's complexity (3 params, 0% schema coverage, no annotations), the description is inadequate. It lacks guidance on when to use it, what the four sites are, and how subdir behaves. Completeness is partial at best.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain parameter meanings. It only clarifies 'timeout' (total seconds). The 'url' parameter's expected format is vaguely implied by 'work page URLs from four sites,' but 'subdir' is completely unexplained. Without schema descriptions, this leaves the agent guessing on two of three parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: identifying and downloading work-page URLs from four specific sites. It distinguishes from generic download tools by specifying the accepted URL type, but it does not name the four sites or explicitly contrast with sibling tools like download_post or download_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a constraint (does not accept arbitrary direct file links) but offers no guidance on when to use this tool versus alternatives like search, get_post, or download_search. It doesn't state prerequisites or exclusions beyond the direct-link restriction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_postC

作品完整元数据。post_id 为数字;ehentai 为 gid/token。

ParametersJSON Schema
NameRequiredDescriptionDefault
siteYes
post_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral disclosure burden. It only mentions the outcome (complete metadata) and a post_id format note, with no statement on read-only behavior, side effects, permissions, rate limits, or error conditions. This is insufficient for an agent to safely predict the tool's effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very compact: two sentences. The first sentence delivers the core purpose, the second adds essential post_id semantics. There is no filler, and the structure is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the output schema exists and the parameter count is low, the description leaves critical context unanswered: possible 'site' values, how site and post_id interact, and when to use this tool over the siblings. An agent cannot fully infer the correct invocation just from this description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema coverage at 0%, the description partially compensates by clarifying that post_id should be numeric and that for ehentai it should be a gid/token pair. This adds real meaning to one parameter, but the 'site' parameter is left completely unexplained (allowed values, enums, or relationship to ehentai are not addressed).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states that the tool retrieves complete metadata (完整元数据) for a work, giving a clear verb-resource pairing. It implies a 'get' operation with metadata as the deliverable, but it does not explicitly name how it differs from siblings like download_post or search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool versus existing alternatives such as search, download_post, or download_url. It lacks explicit conditions, contextual scenarios, or exclusion criteria that would help an agent choose this tool correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

self_checkA

并行检查四站凭证及 API 连通性,每站最多 45 秒;不下载媒体、不返回凭证。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations present, the description takes on the transparency burden and does a strong job: it states the parallel behavior, per-call timeout, and explicitly rules out downloading media and returning credentials. It does not mention whether the check has side effects, such as logging or rate-limit consumption, but the read-only intent is reasonably clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that front-loads the main action, then appends two useful exclusions and a timeout constraint. It is efficient and adds no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool takes no parameters and an output schema exists, the description covers the key operational context: it is parallel, bounded by a 45-second timeout, and intentionally avoids downloading or returning credentials. It does not explain what the four stations are or how results are reported, but these are likely covered by the output schema and domain conventions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the schema already fully covers the input side. The description adds no parameter detail, but none is needed; the baseline of 4 reflects that there is no parameter ambiguity to resolve.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('并行检查' / check in parallel) and a concrete resource ('四站凭证及 API 连通性'), and further clarifies what the tool does not do ('不下载媒体、不返回凭证'). This distinguishes it from retrieval/download-oriented siblings like search, get_post, and download_url.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The purpose implies this is a preflight/diagnostic tool for checking credentials and connectivity before other operations, but it does not explicitly say when to use it instead of siblings or exclude alternative workflows. The 'does not download media' hint helps somewhat, but there is no direct usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.2.0
    • First observeddownload_post
    • First observeddownload_search
    • First observeddownload_url
    • First observedget_post
    • First observedsearch
    • First observedself_check

TDQS

A3.7/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a distinct operation: searching, fetching metadata, downloading by ID, downloading via search, downloading via URL, and running connectivity checks. There is minimal overlap, and the descriptions clarify the boundaries between similar actions.

Naming Consistency4/5

Tool names follow a clear verb-based snake_case pattern (search, get_post, download_post, download_search, download_url). The slight exception is self_check, which breaks the verb-first pattern but remains readable and unambiguous.

Tool Count5/5

Six tools fit the site-specific media downloader role well, providing all necessary operations without bloat. Each tool serves a clear purpose, and the count is well within the typical and manageable range.

Completeness5/5

The tool surface covers the full workflow: search, metadata retrieval, single-post downloads, batch search downloads, URL-based downloads, and credential/connectivity self-checks. Download limitations are handled through documented fallbacks, leaving no obvious dead ends for agents.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers