Humanread MCP server
Commit Oct 31, 2026Enables AI agents to write, format, translate, and publish multilingual novels to the Humanread platform using Markdown or semantic HTML.
Also known as humanread-content/humanread-agent-kit
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 31, 2026
- License
- MIT
What is Humanread MCP?
Humanread enables AI agents to write, format, translate, and publish multilingual novels to the Humanread platform using Markdown or semantic HTML.
Summary generated from the project's README
About Humanread MCP server
Publishing multilingual novels and managing manuscripts through an AI agent is what this MCP server enables. It allows authors to transform Markdown, semantic HTML, or plain text into formatted digital books on the Humanread platform. By connecting an AI client to this server via stdio or Docker, users can automate the creation of works, chapter uploads, and metadata editing while maintaining strict control over prose and layout.
The system focuses on safety by restricting manuscripts to controlled typography and themes, forbidding JavaScript, raw CSS, or tracking elements. Authors use a specific review workflow to inspect live previews and immutable snapshots before final publication. The server handles multilingual fiction by creating authorized translations that remain tied to an original source version. To use it, developers must generate an API key through the Humanread Author Studio and provide it to their MCP client via environment variables or authorization headers.
What you can do with it
- 1Convert manuscripts to themed booksTransform a raw Markdown manuscript into a professionally formatted online book with specific typography and spacing.
- 2Verify layout before publishingReview an exact visual layout of a chapter to ensure the agent has formatted the prose correctly before it goes live.
- 3Manage multilingual editionsCreate and maintain translated versions of a story that are permanently linked to the original source text.
- 4Automate novel publishing workflowsConnect a creative writing agent to a structured API to handle the entire lifecycle of uploading and publishing chapters.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
HUMANREAD_API_KEY
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablehumanread-content/humanread-agent-kit is public and reachablegithub.com/humanread-content/humanread-agent-kit ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/humanread-content/humanread-agent-kit ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubHumanread MCP Server & AI Novel Publishing Skill
Official open-source Model Context Protocol (MCP) server and AI agent skill for 人閱 Humanread, a multilingual novel publishing and reading platform. It helps authors use an AI writing agent to upload, safely format, preview, review, translate, and publish novels written in Markdown, semantic HTML, or plain text.
人閱 Humanread 的開源 MCP Server 與 AI Agent Skill,支援 AI 小說創作、Markdown/HTML 安全排版、多語翻譯、版本審閱及小說發布。
This repository contains client-side integration code only. The Humanread platform backend, database, deployment configuration, abuse controls, and private content storage are not included.
Features
- AI-assisted novel publishing: create works, upload chapters, edit metadata, and publish through MCP tools.
- Share-ready editions: agents can prepare safe 1200×630 book and chapter cards that publish into immutable public Git snapshots.
- Markdown and safe HTML formatting: preserve author-controlled prose and semantic layout without JavaScript, raw CSS, SVG, iframes, or tracking.
- Author review workflow: share a live preview, create an immutable review snapshot, and publish only the approved version.
- Readable themes: configure controlled typography, line height, paragraph spacing, alignment, accent color, drop caps, and scene breaks.
- Multilingual fiction and translation: create authorized translations tied to an immutable source version.
- Images in Git-backed works: upload safely re-encoded PNG, JPEG, or WebP assets with alt text.
- Git publication snapshots: receive source/public commit hashes, tags, reading URLs, and a public repository URL after publication.
- Rights-aware agent workflow: use the author's standing publication authorization and selected reader license.
- Docker and stdio support: run locally as a Python MCP server or in a container.
Use cases
- Connect an AI coding or writing agent to a structured novel publishing API.
- Turn a Markdown manuscript into a safely themed online book.
- Let an author inspect the exact layout before an agent publishes it.
- Maintain original and translated editions without silently rebasing translations.
- Build an MCP-compatible creative-writing or authoring workflow around Humanread.
Repository contents
mcp_server/server.py MCP server, tools, prompts, and resources
skills/humanread-publisher/SKILL.md Agent workflow and safe-formatting rules
Dockerfile Containerized stdio/HTTP runner
Get an API key
- Sign in at https://humanread.surl.tw/login with Google and accept the current terms.
- Open Author Studio and generate an API key. Choose the standing publication license and confirm the publishing conditions.
- Store the key only in your MCP client's secret environment or authorization-header setting. Never paste it into chat, a novel, an issue, source control, or an image.
Run over stdio
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
HUMANREAD_API_KEY='hr_REPLACE_IN_PRIVATE_CONFIG' python -m mcp_server.server --transport stdio
The production API is the default. For a local Humanread development server, set HUMANREAD_API_URL and APP_URL explicitly.
Run with Docker
docker build -t humanread-agent-kit .
docker run --rm -i \
-e HUMANREAD_API_KEY='hr_REPLACE_IN_PRIVATE_CONFIG' \
humanread-agent-kit
Do not put a real key in a Dockerfile, Compose file committed to Git, shell history, or the command examples you share with others. Prefer your MCP client's secret store.
Install the skill
The skill source is skills/humanread-publisher/SKILL.md. Install the whole skills/humanread-publisher directory in your agent's supported skill location, then connect the humanread MCP server.
The skill intentionally forbids JavaScript, CSS, SVG, remote images, forms, iframes, tracking, and unsupported HTML in manuscripts. Appearance is configured through Humanread's safe theme tokens.
Security
Do not open a public issue containing credentials, personal data, private manuscript text, unpublished repository URLs, or working exploit payloads. Follow SECURITY.md for vulnerability reports.
License and marks
The code and documentation in this repository are available under the MIT License. “Humanread”, “人閱”, and the Humanread logo are names and marks of SURL; the software license does not grant permission to imply endorsement or impersonate the official service. See TRADEMARKS.md.
Humanread MCP questions
Can I use JavaScript or custom CSS in my manuscripts?
No, the system intentionally forbids JavaScript, CSS, SVG, and other unsupported HTML to ensure safe formatting.
How is the published content stored?
Published works are stored as immutable public Git snapshots, providing commit hashes and reading URLs.