Transkribus

transkribus-mcp-server

MCP server for the Transkribus REST API. Manage collections, documents, HTR/OCR recognition, models, and more through the Model Context Protocol.

304 tools by default, or 306 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 — 300 tools;

- the Processing API, OIDC bearer auth via account.readcoop.eu — 4 transkribus_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

npm install -g @lazyants/transkribus-mcp-server

Or run directly:

npx @lazyants/transkribus-mcp-server

Configuration

Transkribus uses session-based authentication. Credentials are resolved in this order, per value:

1. OS keyring (recommended — nothing is written to a config file in clear text)
2. Environment variable (TRANSKRIBUS_USER + TRANSKRIBUS_PASSWORD, or TRANSKRIBUS_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:

security add-generic-password -s "transkribus-mcp" -a "user" -w

security add-generic-password -s "transkribus-mcp" -a "password" -w

[!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 -E shows those).

The prompt below is plain POSIX, so it behaves the same in zsh and bash:

`bash

npm install -g @lazyants/transkribus-mcp-server # the keyring module ships with it

cd "$(npm root -g)/@lazyants/transkribus-mcp-server"

printf 'Transkribus password: ' >&2; stty -echo; IFS= read -r TK_SECRET; stty echo; printf '\n' >&2

printf '%s' "$TK_SECRET" | node -e '

const { Entry } = require("@napi-rs/keyring");

let value = "";

process.stdin.setEncoding("utf8");

process.stdin.on("data", (chunk) => { value += chunk; });

process.stdin.on("end", () => {

new Entry("transkribus-mcp", "password").setPassword(value);

console.log("stored");

});

'

unset TK_SECRET

`

Repeat with "user" in place of "password". A different Node.js

installation later (a nvm switch, 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 . — user.transkribus-mcp and password.transkribus-mcp for the default service — which is exactly what the server reads back:

Add-Type -Namespace TranskribusKeyring -Name Native -MemberDefinition @'

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] public struct CREDENTIAL { public uint Flags; public uint Type; [MarshalAs(UnmanagedType.LPWStr)] public string TargetName; [MarshalAs(UnmanagedType.LPWStr)] public string Comment; public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten; public uint CredentialBlobSize; public IntPtr CredentialBlob; public uint Persist; public uint AttributeCount; public IntPtr Attributes; [MarshalAs(UnmanagedType.LPWStr)] public string TargetAlias; [MarshalAs(UnmanagedType.LPWStr)] public string UserName; } [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)] public static extern bool CredWriteW(ref CREDENTIAL credential, uint flags); '@

function Set-TranskribusCredential { param(Parameter(Mandatory)$Account, Parameter(Mandatory)$Prompt) $secure = Read-Host -AsSecureString $Prompt $blob = [Runtime.InteropServices.Marshal]::SecureStringToCoTaskMemUnicode($secure) try { $cred = New-Object TranskribusKeyring.Native+CREDENTIAL $cred.Type = 1 # CRED_TYPE_GENERIC $cred.Persist = 2 # CRED_PERSIST_LOCAL_MACHINE $cred.TargetName = "$Account.transkribus-mcp" # " . " $cred.UserName = $Account $cred.CredentialBlob = $blob $cred.CredentialBlobSize = $secure.Length * 2 # UTF-16 bytes, no terminator if (-not [TranskribusKeyring.Native]::CredWriteW([ref]$cred, 0)) { throw "CredWrite failed (Win32 error $([Runtime.InteropServices.Marshal]::GetLastWin32Error()))" } Write-Host "Stored '$Account' in Windows Credential Manager." } finally { [Runtime.InteropServices.Marshal]::ZeroFreeCoTaskMemUnicode($blob) $secure.Dispose() Remove-Variable secure, blob } }

Set-TranskribusCredential -Account 'user' -Prompt 'Transkribus user (e-mail)' Set-TranskribusCredential -Account 'password' -Prompt 'Transkribus password'

Using a custom TRANSKRIBUS_KEYRING_SERVICE (e.g. acme)? Set TargetName to

user.acme / password.acme to match — the server looks each value up under

. .

Linux

secret-tool store --label="Transkribus user" service transkribus-mcp username user

secret-tool store --label="Transkribus password" service transkribus-mcp username password

(each prompts for the value)

Once stored, MCP config files need no credentials at all.

Use environment variables instead

export TRANSKRIBUS_USER=your-email@example.com

export TRANSKRIBUS_PASSWORD=your-password

Or, with a session you already hold:

export TRANSKRIBUS_SESSION_ID=your-session-id

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:

export TRANSKRIBUS_ACCESS_TOKEN=your-bearer-token       # skip the token exchange entirely

export TRANSKRIBUS_PROCESSING_CLIENT_ID=custom-client # non-default OIDC client

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: pass processId and optionally interval (an int32 number of milliseconds). The call returns the observed job with timedOut: false; inspect terminal because 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: pass processId to download a finished job's archive. The result includes filename, mimeType: "application/zip", encoding: "base64", byteLength, and data; decode data as base64 and save it under filename. 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

| `transkribus-mcp-transcri