
Transkribus
io.github.lazyants由 GitHub 帳號 lazyants 發布v4.2.0更新於 Nov 14, 2026
Transkribus REST and Processing APIs — collections, HTR/OCR; default v1, optional v2 beta.
概覽
非官方 Transkribus MCP 伺服器:讓助理管理館藏、上傳文件並執行 HTR/OCR 辨識工作。
- 可以做什麼
- 管理館藏、文件、頁面、使用者、標籤、額度與活動紀錄
- 將頁面影像或 PDF 上傳至館藏並查詢上傳狀態
- 執行 HTR/OCR 辨識、版面分析與 PyLaia/P2PaLA 工作並讀取結果
- 瀏覽與管理辨識模型、工作與操作
- 檢索館藏並執行關鍵字定位
- 提交 Processing API 工作並取得 PAGE/ALTO XML 或結果壓縮檔
- 適用情境
- 當你使用 Transkribus 對手寫文字或掃描文件進行辨識,並希望助理在對話中直接操作館藏、上傳、辨識工作與結果時適用。拆分入口可只載入需要的功能領域。
- 執行需求
- 透過 npx 或全域 npm 安裝在本機執行(需要 Node.js)。需要 Transkribus 帳號:TRANSKRIBUS_USER 加 TRANSKRIBUS_PASSWORD,或既有的 TRANSKRIBUS_SESSION_ID,建議存放在作業系統鑰匙圈(服務名稱由 TRANSKRIBUS_KEYRING_SERVICE 指定)。選用的 TRANSKRIBUS_ACCESS_TOKEN 可略過 Processing API 的權杖交換。需要連線至 Transkribus 網路端點。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Transkribus,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
transkribus-mcp-server
MCP server for the Transkribus REST API. Manage collections, documents, HTR/OCR recognition, models, and more through the Model Context Protocol.
305 tools by default, or 307 with Processing v2, across 23 resource domains, with 9 entry points so you can pick the right server for your MCP client's tool limit.
API scope: This server covers two Transkribus APIs:
- the legacy TrpServer REST API (
https://transkribus.eu/TrpServer/rest), session-based — 301 tools;- the Processing API, OIDC bearer auth via
account.readcoop.eu— 4transkribus_processing_*tools with the default Metagrapho v1 backend (https://transkribus.eu/processing/v1), or 6 with the optional Developer Platform v2 beta (https://api-staging.transkribus.org/v2).v2 requires explicit selection. Its published OpenAPI names a staging server; production v2 availability has not been confirmed. Both backends take
config.textRecognition.htrId.
Installation
Or run directly:
Configuration
Transkribus uses session-based authentication. Credentials are resolved in this order, per value:
- OS keyring (recommended — nothing is written to a config file in clear text)
- Environment variable (
TRANSKRIBUS_USER+TRANSKRIBUS_PASSWORD, orTRANSKRIBUS_SESSION_ID)
Either a user name and password (the server logs in and manages the session) or a session id you already hold. A session id takes precedence when both are available; it expires, so a user name and password is the better choice for a long-running setup — and is what lets the server re-authenticate after a 401.
The keyring is never required: if it is unavailable — a headless Linux box with
no Secret Service, an unsupported platform, an install with --omit=optional —
or if it does not answer within 5 seconds, the server falls back to the
environment.
Store the credentials in the OS keyring
Three entries under one service name, transkribus-mcp by default:
user, password and session-id (store only what you use).
[!IMPORTANT] The commands below read the value from an interactive prompt rather than taking it as an argument, so it never lands in your shell history, in a command line, or in the launch environment of another process. Avoid pasting a password directly onto the command line.
macOS
Omitting the value after -w makes security prompt for it:
[!NOTE] A login-keychain item belongs to the program that created it. The first time the server reads an item created by
security, macOS shows a "…wants to use your confidential information stored in transkribus-mcp" dialog — choose Always Allow and it will not ask again. Until that is granted the read cannot complete: the server waits 5 seconds, then falls back to the environment variables, so a server started where nobody can answer the dialog behaves as if the keyring were empty rather than hanging.To avoid the dialog entirely, write the entry from the same Node.js runtime that will read it. The value is piped in on standard input, so it appears neither in a command line nor in a process environment (
ps -Eshows those). The prompt below is plain POSIX, so it behaves the same inzshandbash:Repeat with
"user"in place of"password". A different Node.js installation later (anvmswitch, say) is a different program to the keychain, so the dialog can appear once more for it.
Windows (PowerShell)
cmdkey can only take the value as a command-line argument, which exposes it in
the process list. Read it from a hidden prompt instead and write it straight into
Windows Credential Manager via CredWrite. The credential's target name is
<account>.<service> — user.transkribus-mcp and password.transkribus-mcp
for the default service — which is exactly what the server reads back:
Using a custom
TRANSKRIBUS_KEYRING_SERVICE(e.g.acme)? SetTargetNametouser.acme/password.acmeto match — the server looks each value up under<account>.<service>.
Linux
Once stored, MCP config files need no credentials at all.
Use environment variables instead
Or, with a session you already hold:
Environment variables
Processing API credentials
The transkribus_processing_* tools talk to a different service with a different
auth scheme, but they need no extra configuration: the same
TRANSKRIBUS_USER + TRANSKRIBUS_PASSWORD are exchanged for an OIDC bearer token
(READCOOP SSO password grant, client processing-api-client) and refreshed
automatically. TRANSKRIBUS_SESSION_ID does not apply to them.
Two optional overrides:
Optional Processing v2 beta
Set TRANSKRIBUS_PROCESSING_BACKEND=v2 in the MCP server's environment before
starting it. The default is v1; invalid values fail configuration. v2 uses
the documented staging host https://api-staging.transkribus.org/v2, with the
same OIDC credentials and PAGE/ALTO XML operations as v1. This selection affects
the Processing tools in both the full server and transkribus-mcp-processing.
v2 submission and status results preserve the API fields and add terminal,
pollingAvailable, and linksByRel. Links are indexed by their stable rel
values, such as self, status, longpoll, result, and page-result;
display titles do not affect behavior. An absent longpoll relation stops
polling availability, and terminal states always stop it. Link URLs are returned
as data; the server requests only the selected backend's documented paths.
transkribus_processing_longpoll: passprocessIdand optionallyinterval(an int32 number of milliseconds). The call returns the observed job withtimedOut: false; inspectterminalbecause HTTP 200 may contain a nonterminal status change. HTTP 408 or the 45-second local deadline returns{ processId, timedOut: true, terminal: null }, so callers may retry without treating a timeout as a completed job.transkribus_processing_get_result_zip: passprocessIdto download a finished job's archive. The result includesfilename,mimeType: "application/zip",encoding: "base64",byteLength, anddata; decodedataas base64 and save it underfilename. Downloads are limited to 20 MiB, checked for ZIP MIME type and signature, and do not follow redirects. HTTP 404 means no result is available.
These two tools are advertised only with v2 selected. The job guide
describes lifecycle, links, and retention; the compatibility guide
documents the Developer Platform's existing /v2/processes contract.
Entry Points
Use split servers to reduce context size — pick only the splits you need.
Uploading a document
To ingest a document, use this three-step flow:
transkribus_upload_create_structure— give itcollId, atitle, and apagesarray of{ fileName, pageNr }(one entry per page image you are about to send). Returns an upload with anuploadId.transkribus_upload_page— call once per page with theuploadIdandimagePath(a path to a local image file), optionallypageXmlPathfor an existing PAGE XML transcript.transkribus_upload_get_status— poll with theuploadIduntil the document appears in the collection.
These upload tools ship in the full transkribus-mcp-server and in the transkribus-mcp-admin
split — not in transkribus-mcp-collections.
Uploading a PDF
transkribus_coll_create_doc_from_pdf creates a document from a local PDF in one call. Give it
collId and pdfFilePath (a path to a local PDF file), and optionally a title and
doDeleteImportSource. The file must start with the %PDF- header; anything else is refused
before a request is sent. The tool returns the API's response unchanged. It ships in the full
transkribus-mcp-server and in the transkribus-mcp-collections split — not in
transkribus-mcp-admin.
You can still convert the PDF to page images yourself and use the three-step flow above, for example to control the image format or resolution.
Claude Code
Add to ~/.claude/settings.json. With the credentials in the OS keyring under
the default service name (recommended), no env key is needed:
Or use split servers (pick the splits you need):
Two Transkribus accounts at once — one instance per account, each pointed at its own keyring service name:
Without a keyring, pass the credentials in env instead:
Claude Desktop
Add to claude_desktop_config.json. With the credentials in the OS keyring
(recommended — assumes the default service name transkribus-mcp):
Without a keyring:
Security
- Use the OS keyring to keep your password out of config files and shell history entirely (see Configuration)
- Never commit your credentials to version control
- Session IDs expire — prefer a user name and password for long-running setups; a session id alone cannot be renewed after a 401
Disclaimer
This is an unofficial MCP server for Transkribus. The authors are not affiliated with READ-COOP SCE. Use at your own risk.
Releasing
Releases ship via the GitHub Release event. Maintainer flow:
-
Bump the version in
package.json,package-lock.json, andserver.json(npm version <x.y.z> --no-git-tag-versionupdates the first two together).npm run check-versionshard-fails unlesspackage.json#/versionandserver.json#/packages[0].versionagree.server.json#/versionis checked loosely: it must be present, and it only fails when it regresses belowpackages[0].version— a value left behind at the previous release passes with aWARN:line and exit 0. The script does not look atpackage-lock.jsonorCHANGELOG.mdat all, so read its output rather than trusting its exit code. -
Update
CHANGELOG.md. -
Commit, and merge the version bump to
mainbefore creating the release. Then create the tag yourself, on a SHA you have checked, and only then create the release from it:The failure this prevents: with no existing tag,
gh release create vX.Y.Zplaces one on the tip of the default branch. Run it while the bump is still on a release branch and it tags the previous release's commit; the workflow then publishes whatever version it finds in that commit'spackage.json, producing avX.Y.ZGitHub Release that silently republishes the old version. The publish workflow now refuses to continue whenGITHUB_REF_NAMEis notv<package.json version>, so that exact scenario fails beforenpm publishrather than silently republishing. The sequence above is still required, and guards a case the workflow cannot: the workflow guard only runs once a release already exists, and it passes for any commit carrying the right version — so it catches a mis-tagged release, not the wrong commit being tagged.Each element is load-bearing:
gh pr view … .mergeCommit.oidnames the release PR's own squash commit. Do not substitutegit rev-parse origin/main: that is merely whatever sits onmainat the moment you look, so an unrelated merge landing in the gap gets tagged and shipped instead.ghexits 0 and prints nothing for an unmerged PR, hence the explicittest -n.- The
&&chain stops at the first failure instead of falling through to the irreversible step. Bothgit showcalls are assigned to a variable rather than piped directly, so their exit status is actually checked — a pipeline reports only its last command's status unlesspipefailis set, which is not assumed here. git merge-base --is-ancestorproves the commit is reachable frommain. Mere existence is not enough: a commit can be present locally because another branch was fetched, and if its version files happen to match it would otherwise pass every remaining check.- The version test reads
package.jsonout of the target commit, not the working tree — which would still show the right version while$SHApointed elsewhere. - The
awklifts that version's section out of the commit'sCHANGELOG.mdfor--notes-file. Without it the release body is whatever--notes-from-tagfinds in the annotation — here the literal stringvX.Y.Z, a poor release note for any version and a misleading one for a release carrying a breaking change. It stops at the next## [heading or at the first link-reference definition, because the oldest entry has no heading after it and would otherwise swallow the whole link-reference block.grep -qrather thantest -sguards the result: a section empty apart from its blank line still produces a one-byte file, whichtest -saccepts. --verify-tagmakesghabort rather than invent a tag if the push did not land — the guard against the tip-of-default-branch fallback described above.
If
gh release createfails after the tag is already pushed, do not rerun the whole block; it will stop atgit tag, which is correct. Rerun only the final command. -
The
Publish to npm + MCP Registryworkflow runs automatically: itnpm publishes with provenance, polls the registry until the tarball is available, then pushes the matchingserver.jsonto the MCP Registry viamcp-publisher.
The workflow skips npm publish cleanly if the version is already on npm (cutover guard for releases that were partially published manually).
npm authentication
Publishing uses npm Trusted Publishing: the workflow's GitHub OIDC token (id-token: write) is exchanged for a one-shot publish token at runtime. No NPM_TOKEN secret needs to live in the repo.
The binding is configured in the npm web UI (package → Trusted Publishers): provider GitHub Actions, organization lazyants, repository transkribus-mcp-server, workflow publish-registry.yml.
License
FSL-1.1-MIT — see LICENSE for the full terms. Versions 1.x remain MIT-licensed.
來源:README.md,提交 679eb7e
工具
0版本歷史
4- v4.2.0最新Nov 14, 2026
- v4.1.1Nov 7, 2026
- v4.1.0Oct 3, 2026
- v4.0.0Sep 16, 2026
評分
已滿足適用檢查項的 40%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分
請在儲存庫或註冊中心條目中宣告授權條款。