EH Index MCP

A read-only MCP server for searching and exploring E-Hentai and ExHentai.

English | 简体中文

Search galleries, follow version chains, resolve image pages, inspect metadata, translate tags, and organize related uploads without modifying your account.

Quick start · What it does · Tool catalog · Authentication · Development

What it does

EH Index MCP exposes 30 read-only tools. It does not modify watched tags or favorites, purchase archives, download galleries, or upload local files.

Related MCP server: mangadex-mcp

Quick start

Run with npx

npx -y eh-index-mcp

Public E-Hentai search and metadata work without an account.

Add it to an MCP client

{
  "mcpServers": {
    "eh-index": {
      "command": "npx",
      "args": ["-y", "eh-index-mcp"]
    }
  }
}

Restart the client after saving the configuration. The server communicates over stdio and writes protocol messages only to stdout.

npm install --global eh-index-mcp
eh-index-mcp

Requires Node.js 20.3 or newer.

Common workflows

Find galleries related to one upload

Use eh_find_similar_galleries with a gallery URL or gid and token. The tool follows EhViewer's search strategy:

1. Extract a stable title from structural wrappers such as event, group, language, and edition markers.

2. Search the extracted title as an exact phrase.

3. Fall back to the first artist tag, then the uploader, when no usable title remains.

The response reports the selected strategy and native query alongside the gallery results.

Turn search results into works and series

eh_search_gallery_works scans up to ten result pages and organizes the response into:

• gallery uploads;

• likely variants of the same work;

• related works grouped into series;

• official parent/newer-version relationships;

• confidence levels and complete source-gallery references.

The grouping logic reports whether each work came from an official version chain, a heuristic normalized-title-and-creator match, or a standalone fallback. Low-confidence items remain separate.

Search across a controlled page budget

eh_search_galleries_batch scans up to ten ordinary search pages without fetching gallery metadata. It deduplicates gallery references, reports the pages scanned, and returns a resume cursor when the requested page budget truncates the scan.

Read Watched Tags without changing account state

eh_search_watched reads the authenticated Watched Tags feed using the same native query, category, advanced-filter, and cursor controls as ordinary search. It never changes watched tags or other account settings.

Search from a local image

eh_search_by_file reads one explicit local file, calculates its SHA-1 digest, and performs an exact hash search. The image is never uploaded. Relative paths, directories, wildcards, and files above the configured size limit are rejected.

Resolve Chinese tag names

eh_search_translated_tags maps Chinese translated names and English originals to formal E-Hentai tags. Results include a native query fragment ready for eh_search_galleries. Matching handles Unicode width, punctuation, symbols, and spacing while preserving the source text.

Tool catalog

Built-in prompts

The server provides four built-in prompts for common read-only workflows:

• eh_gallery_research — search and investigate related galleries;

• eh_gallery_compare — compare two gallery versions;

• eh_gallery_version_audit — audit a gallery version chain;

• eh_tag_research — resolve and investigate native tags.

Authentication

Authentication is optional. Public E-Hentai tools work without cookies. Favorites, archive metadata, and ExHentai require identity cookies from a browser session you control.

Never provide an account password. Store cookie values in the MCP host's environment or secret manager rather than committing them to a configuration file.

{
  "mcpServers": {
    "eh-index": {
      "command": "npx",
      "args": ["-y", "eh-index-mcp"],
      "env": {
        "EH_MEMBER_ID": "your_ipb_member_id",
        "EH_PASS_HASH": "your_ipb_pass_hash",
        "EH_IGNEOUS": "your_igneous_cookie"
      }
    }
  }
}

The server sends identity cookies only to E-Hentai and ExHentai hosts. Tools never return cookie values, and the server does not log them.

Safety model

Configuration

The defaults are conservative for E-Hentai's shared-IP limits. Increase intervals rather than lowering them when several clients share one exit address.

All values must be non-negative integers.

If Node.js 24 or newer reaches E-Hentai through an HTTP proxy, pass HTTP_PROXY, HTTPS_PROXY, and NODE_USE_ENV_PROXY=1 to the server process.

Data sources and attribution

• Gallery data comes from E-Hentai and ExHentai pages and APIs.

• Similar-gallery title extraction is adapted from EhViewer under Apache-2.0. See THIRD_PARTY_NOTICES.md.

• Tag translations are fetched at runtime from EhTagTranslation/Database. The database is not bundled with this package and remains under its own per-file notices and CC BY-NC-SA 3.0 CN license.

• Tag definitions come from EHWiki and are returned with source URLs as untrusted external content.

Development

npm install
npm run check
npm run pack:smoke
npm run smoke

npm run check builds the project and runs the automated test suite. npm run pack:smoke installs a local tarball in a temporary directory and verifies stdio initialization, the tool list, output schemas, and read-only annotations. npm run smoke exercises the built stdio server against a small public live-data workflow without downloading gallery images or torrent files.

The repository also includes a multi-stage Dockerfile for a production Node.js image. Build and start it with:

docker build -t eh-index-mcp .
docker run --rm -i eh-index-mcp

The container communicates over stdio and accepts the same optional cookie and tuning environment variables as the native Node.js process.

An optional authenticated smoke test is available for maintainers with existing cookies:

npm run smoke:auth

It performs read-only checks and suppresses credentials, gallery identifiers, titles, category names, and notes from its output.

Acknowledgements

EH Index MCP builds on the work of the following projects and communities:

• E-Hentai and ExHentai for the gallery platform and public interfaces.

• EhViewer-NekoInverter for the similar-gallery title extraction strategy.

• EhTagTranslation for the Chinese tag translation database.

• EHWiki for structured tag definitions.

• Model Context Protocol TypeScript SDK for the MCP server foundation.

Their respective content, data, and source code remain subject to their own licenses.

Project links

• npm package

• Source code

• Issue tracker

• Releases

Disclaimer

EH Index MCP is an unofficial community project. It is not affiliated with, endorsed by, or operated by E-Hentai, ExHentai, or their operators. Users are responsible for complying with applicable laws, site rules, and account requirements. Site availability, page structure, and returned data may change without notice.

License

The project source code is available under the MIT License. Third-party data and adapted logic retain their respective licenses as described above and in THIRD_PARTY_NOTICES.md.