transkribus

transkribus-mcp-server

用于 Transkribus REST API 的 MCP 服务。通过模型上下文协议管理馆藏、文档、HTR/OCR 识别、模型等。

默认提供 304 个工具，启用 Processing v2 后为 306 个工具，涵盖 23 个资源域，并提供 9 个入口点，让你可以根据 MCP 客户端的工具数量限制选择合适的服务。

**API 范围：**此服务涵盖 两个 Transkribus API：

• 旧版 TrpServer REST API（https://transkribus.eu/TrpServer/rest），基于会话，共 300 个工具；
• Processing API，通过 account.readcoop.eu 使用 OIDC 持有者身份验证，默认使用 Metagrapho v1 后端（https://transkribus.eu/processing/v1）时提供 4 个 transkribus_processing_* 工具，使用可选的 Developer Platform v2 beta 时提供 6 个（https://api-staging.transkribus.org/v2）。

v2 需要显式选择。其已发布的 OpenAPI 指定了一个暂存服务器；尚未确认 v2 是否可在生产环境中使用。两个后端都使用 config.textRecognition.htrId。

安装

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

或者直接运行：

npx @lazyants/transkribus-mcp-server

配置

Transkribus 使用基于会话的身份验证。凭据按以下顺序逐项解析：

1. 操作系统密钥环（推荐——不会以明文形式写入配置文件）
2. 环境变量（TRANSKRIBUS_USER + TRANSKRIBUS_PASSWORD，或 TRANSKRIBUS_SESSION_ID）

可以使用用户名和密码（由服务器登录并管理会话），也可以使用你已有的会话 ID。如果两者都可用，则优先使用会话 ID；会话 ID 会过期，因此对于长期运行的配置，用户名和密码是更好的选择，而且服务器在收到 401 后可以使用它们重新进行身份验证。

密钥环并非必需：如果密钥环不可用——例如没有 Secret Service 的无头 Linux 设备、不受支持的平台，或使用 --omit=optional 安装——或者密钥环在 5 秒内没有响应，服务器就会回退到环境变量。

将凭据存入操作系统密钥环

默认使用同一个服务名称 transkribus-mcp，存储三个条目：user、password 和 session-id（只存储你实际使用的条目）。

重要

以下命令会通过交互式提示读取值，而不是将值作为参数传入，因此值不会出现在 shell 历史记录、命令行或其他进程的启动环境中。请避免将密码直接粘贴到命令行中。

macOS

省略 -w 后面的值会使 security 提示输入该值：

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

说明

登录钥匙串项目属于创建它的程序。服务器首次读取由 security 创建的项目时，macOS 会显示“……想要使用储存在 transkribus-mcp 中的机密信息”对话框——选择 始终允许，之后便不会再询问。在授予权限之前，读取无法完成：服务器会等待 5 秒，然后回退到环境变量，因此，在无人能回应对话框的情况下启动服务器，其表现会像钥匙串为空，而不是一直挂起。

若要完全避免此对话框，请使用之后负责读取项目的同一个 Node.js 运行时写入条目。值通过标准输入传入，因此既不会出现在命令行中，也不会出现在进程环境中（ps -E 可以看到这些内容）。下面的提示符采用纯 POSIX 语法，因此在 zsh 和 bash 中的行为相同：

npm install -g @lazyants/transkribus-mcp-server   # keyring 模块随其一同安装
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

将 "password" 替换为 "user"，重复上述操作。之后若使用不同的 Node.js 安装（例如切换 nvm 版本），钥匙串会将其视为不同的程序，因此可能会再次显示对话框。

Windows（PowerShell）

cmdkey 只能将值作为命令行参数传入，这会导致它出现在进程列表中。改为从隐藏提示中读取，并通过 CredWrite 直接写入 Windows Credential Manager。凭据的目标名称为 <account>.<service>——默认服务对应 user.transkribus-mcp 和 password.transkribus-mcp——服务器读取时使用的名称与此完全一致：

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)][string]$Account, [Parameter(Mandatory)][string]$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"   # "<account>.<service>"
        $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'

使用自定义的 TRANSKRIBUS_KEYRING_SERVICE（例如 acme）？请将 TargetName 设为 user.acme / password.acme，以保持一致——服务器会通过 <account>.<service> 查找各个值。

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)

存储完成后，MCP 配置文件无需包含任何凭据。

改用环境变量

export [email protected]
export TRANSKRIBUS_PASSWORD=your-password

或者，使用已有会话：

export TRANSKRIBUS_SESSION_ID=your-session-id

环境变量

变量	默认值	描述
TRANSKRIBUS_USER	—	账户电子邮件；配置的服务对应的钥匙串中没有 user 条目时使用
TRANSKRIBUS_PASSWORD	—	账户密码；钥匙串中没有 password 条目时使用
TRANSKRIBUS_SESSION_ID	—	现有会话 ID；钥匙串中没有 session-id 条目时使用
TRANSKRIBUS_KEYRING_SERVICE	transkribus-mcp	钥匙串服务名称。可覆盖此值以同时连接多个 Transkribus 账户——每个账户运行一个服务实例，并使用各自的服务名称

配置 Processing API 凭据

transkribus_processing_* 工具连接的是采用不同身份验证方案的另一项服务，但无需额外配置：同一组 TRANSKRIBUS_USER 和 TRANSKRIBUS_PASSWORD 会用于换取 OIDC bearer token（READCOOP SSO 密码授权，客户端 processing-api-client），并自动刷新。TRANSKRIBUS_SESSION_ID 不适用于这些工具。

两个可选覆盖项：

export TRANSKRIBUS_ACCESS_TOKEN=your-bearer-token       # skip the token exchange entirely
export TRANSKRIBUS_PROCESSING_CLIENT_ID=custom-client   # non-default OIDC client

可选处理后端 v2 beta

在启动 MCP 服务之前，在其环境中设置 TRANSKRIBUS_PROCESSING_BACKEND=v2。默认值为 v1；无效值会导致配置失败。v2 使用已公开的暂存主机 https://api-staging.transkribus.org/v2，并使用与 v1 相同的 OIDC 凭据和 PAGE/ALTO XML 操作。此选择会影响完整服务和 transkribus-mcp-processing 中的处理工具。

后端	作业标识符	终态	结果保留时间	工具
v1（默认）	正整数，包括数字字符串	FINISHED、FAILED	两天	提交、状态、PAGE XML、ALTO XML
v2（beta，暂存环境）	正整数、数字字符串、UUID	FINISHED、FAILED、CANCELLED	完成后 24 小时	相同的四种工具，另加长轮询和 ZIP

v2 的提交和状态结果会保留 API 字段，并添加 terminal、pollingAvailable 和 linksByRel。链接按稳定的 rel 值索引，例如 self、status、longpoll、result 和 page-result；显示标题不影响行为。缺少 longpoll 关系时会停止轮询，终态也始终会停止轮询。链接 URL 会作为数据返回；服务只请求所选后端已公开的路径。

• transkribus_processing_longpoll：传入 processId，并可选传入 interval（以毫秒为单位的 int32 数值）。调用会返回观察到的作业，并带有 timedOut: false；请检查 terminal，因为 HTTP 200 可能包含非终态状态变化。HTTP 408 或 45 秒的本地截止时间会返回 { processId, timedOut: true, terminal: null }，因此调用方可以重试，而不会将超时误认为作业已完成。
• transkribus_processing_get_result_zip：传入 processId，下载已完成作业的归档文件。结果包含 filename、mimeType: "application/zip"、encoding: "base64"、byteLength 和 data；请将 data 解码为 base64，并以 filename 保存。下载大小限制为 20 MiB，会检查 ZIP MIME 类型和签名，且不会跟随重定向。HTTP 404 表示没有可用结果。

仅在选择 v2 时才会公布这两个工具。作业指南介绍了生命周期、链接和保留期限；兼容性指南记录了 Developer Platform 现有的 /v2/processes 合约。

入口点

命令	领域	工具
transkribus-mcp-server	全部 23 个领域	304（使用 v2 时为 306）
transkribus-mcp-collections	Auth、Collections（core/docs/pages/users/crowd/editdecl/credits/stats/labels/activity/tags）	131
transkribus-mcp-admin	Auth、Admin、Credits、Uploads、Labels、Files、System、Root	62
transkribus-mcp-transcription	Auth、Recognition、Layout Analysis、PyLaia、P2PaLA、DU	47
transkribus-mcp-users	Auth、Users、Crowdsourcing、eLearning	29
transkribus-mcp-models	Auth、Models	26
transkribus-mcp-jobs	Auth、Jobs、Actions	19
transkribus-mcp-search	Auth、Search、KWS	16
transkribus-mcp-processing	Processing — 无旧版身份验证工具	4（使用 v2 时为 6）

使用拆分服务可减少上下文大小——只选择需要的拆分服务。

上传文档

要摄取文档，请按以下三个步骤操作：

1. transkribus_upload_create_structure — 提供 collId、title 和一个 pages 数组，数组元素为 { fileName, pageNr }（每张即将发送的页面图像对应一个元素）。返回的上传对象包含 uploadId。
2. transkribus_upload_page — 每页调用一次，提供 uploadId 和 imagePath（本地图像文件的 路径）；也可选提供 pageXmlPath，用于已有的 PAGE XML 转录文本。
3. transkribus_upload_get_status — 使用 uploadId 轮询，直到文档出现在 集合中。

这些上传工具包含在完整的 transkribus-mcp-server 和拆分版 transkribus-mcp-admin 中，transkribus-mcp-collections 不包含这些工具。不支持摄取 PDF；请先将 PDF 转换为页面图像，再使用上述流程。

Claude Code

添加到 ~/.claude/settings.json。如果凭据存储在 OS 密钥环中，并使用 默认服务名称（推荐），则无需添加 env 键：

{
  "mcpServers": {
    "transkribus": {
      "command": "npx",
      "args": ["-y", "@lazyants/transkribus-mcp-server"]
    }
  }
}

或者使用拆分版服务（选择所需的拆分版）：

{
  "mcpServers": {
    "transkribus-collections": {
      "command": "npx",
      "args": ["-y", "-p", "@lazyants/transkribus-mcp-server", "transkribus-mcp-collections"]
    },
    "transkribus-transcription": {
      "command": "npx",
      "args": ["-y", "-p", "@lazyants/transkribus-mcp-server", "transkribus-mcp-transcription"]
    }
  }
}

同时使用两个 Transkribus 账户 — 每个账户运行一个实例，并分别指向各自的 密钥环服务名称：

{
  "mcpServers": {
    "transkribus-team-a": {
      "command": "npx",
      "args": ["-y", "@lazyants/transkribus-mcp-server"],
      "env": { "TRANSKRIBUS_KEYRING_SERVICE": "transkribus-team-a" }
    },
    "transkribus-team-b": {
      "command": "npx",
      "args": ["-y", "@lazyants/transkribus-mcp-server"],
      "env": { "TRANSKRIBUS_KEYRING_SERVICE": "transkribus-team-b" }
    }
  }
}

如果不使用密钥环，请改为在 env 中传递凭据：

{
  "mcpServers": {
    "transkribus": {
      "command": "npx",
      "args": ["-y", "@lazyants/transkribus-mcp-server"],
      "env": {
        "TRANSKRIBUS_USER": "[email protected]",
        "TRANSKRIBUS_PASSWORD": "your-password"
      }
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json。如果凭据存储在 OS 密钥环中 （推荐 — 假设使用默认服务名称 transkribus-mcp）：

{
  "mcpServers": {
    "transkribus": {
      "command": "npx",
      "args": ["-y", "@lazyants/transkribus-mcp-server"]
    }
  }
}

如果不使用密钥环：

{
  "mcpServers": {
    "transkribus": {
      "command": "npx",
      "args": ["-y", "@lazyants/transkribus-mcp-server"],
      "env": {
        "TRANSKRIBUS_USER": "[email protected]",
        "TRANSKRIBUS_PASSWORD": "your-password"
      }
    }
  }
}

安全

• 使用 OS 密钥环，将密码完全排除在配置文件和 shell 历史记录之外（参见配置）
• 切勿将凭据提交到版本控制中
• 会话 ID 会过期 — 对于长期运行的设置，建议使用用户名和密码；仅凭会话 ID 无法在 401 后续期

免责声明

这是一个非官方的 Transkribus MCP 服务。作者与 READ-COOP SCE 无关。使用风险自负。

发布

发布通过 GitHub Release 事件进行。维护者的操作流程：

1. 更新 package.json、package-lock.json 和 server.json 中的版本（npm version <x.y.z> --no-git-tag-version 会同时更新前两个文件）。如果 package.json#/version 和 server.json#/packages[0].version 不一致，npm run check-versions 会直接失败。对 server.json#/version 的检查较宽松：该字段必须存在，且只有在它低于 packages[0].version 时才会失败 — 如果该值停留在上一个版本，脚本会输出一行 WARN: 并以 0 退出。脚本完全不会检查 package-lock.json 或 CHANGELOG.md，因此请仔细阅读其输出，不要只看退出代码。

2. 更新 CHANGELOG.md。

3. 提交更改，并在创建发布前，先将版本更新合并到 main。然后自行创建标签，确保它指向已核实的 SHA，最后再从该标签创建发布：

   V=X.Y.Z && PR=<release-pr-number> &&
     SHA="$(gh pr view "$PR" --json mergeCommit -q .mergeCommit.oid)" && test -n "$SHA" &&
     git fetch origin main && git merge-base --is-ancestor "$SHA" origin/main &&
     PKG="$(git show "$SHA:package.json")" &&
     test "$(printf '%s' "$PKG" | node -pe 'JSON.parse(require("fs").readFileSync(0,"utf8")).version')" = "$V" &&
     CL="$(git show "$SHA:CHANGELOG.md")" &&
     printf '%s\n' "$CL" | awk -v v="$V" 'index($0,"## ["v"]")==1{f=1;next} /^## \[/{f=0} /^\[[0-9]+\.[0-9]+\.[0-9]+\]:/{f=0} f' > "/tmp/notes-v$V.md" &&
     grep -q '[^[:space:]]' "/tmp/notes-v$V.md" &&
     git tag -a "v$V" "$SHA" -m "v$V" &&
     git push origin "v$V" &&
     gh release create "v$V" --verify-tag --notes-file "/tmp/notes-v$V.md"
   

   此流程可防止的问题： 如果尚无现有标签，gh release create vX.Y.Z 会将标签放在默认分支的最新提交上。如果版本更新仍在发布分支上时运行该命令，它就会为上一个版本的提交打标签；随后工作流会发布该提交 package.json 中的版本，导致 GitHub Release 上的 vX.Y.Z 悄无声息地重新发布旧版本。现在，发布工作流会在 GITHUB_REF_NAME 与 v<package.json version> 不一致时拒绝继续，因此这种情况会在执行 npm publish 前失败，而不是悄无声息地重新发布。上述顺序仍然是必需的，它还可以防范工作流无法处理的情况：工作流守卫只有在发布已创建后才会运行，而且任何包含正确版本的提交都能通过 — 因此它能发现标签错误的发布，却无法发现被打上标签的提交不正确。

   每个环节都至关重要：

   • gh pr view … .mergeCommit.oid 指向发布 PR 自身的 squash 提交。不要用 git rev-parse origin/main 替代：它只会返回你查看时 main 上的提交，因此这段时间内合入的无关提交也会被打上标签并发布。对于尚未合并的 PR，gh 会以 0 退出且不输出任何内容，因此需要显式执行 test -n。
   • && 链会在首次失败时停止，而不会继续执行不可逆的步骤。两个 git show 调用的结果都赋值给变量，而不是直接通过管道传递，因此它们的退出状态会得到实际检查——除非设置了 pipefail（此处未假设已设置），否则管道只会报告最后一个命令的状态。
   • git merge-base --is-ancestor 可证明该提交能从 main 到达。仅仅存在还不够：该提交可能是因为获取了另一个分支而存在于本地；如果其中的版本文件恰好匹配，它就会通过所有剩余检查。
   • 版本检查从目标提交中读取 package.json，而不是读取工作树——如果 $SHA 指向其他提交，工作树中仍可能显示正确的版本。
   • awk 会从该提交的 CHANGELOG.md 中提取对应版本的章节，供 --notes-file 使用。没有它，发布说明就会采用 --notes-from-tag 从注释中找到的内容——此处就是字面字符串 vX.Y.Z，无论哪个版本，这都是糟糕的发布说明；如果此次发布包含破坏性变更，还会造成误导。它会在遇到下一个 ## [ 标题或第一个链接引用定义时停止，因为最早的条目后面没有标题，否则就会把整个链接引用块也一并包含进去。这里使用 grep -q 而不是 test -s 来检查结果：如果章节除了空行之外没有内容，仍会生成一个 1 字节的文件，而 test -s 会将其视为非空。
   • --verify-tag 会让 gh 在推送未成功时中止，而不是自行创建标签——这是针对上文所述默认分支顶端回退行为的保护措施。

   如果 gh release create 在标签已经推送后失败，不要重新运行整个代码块；它会在 git tag 处停止，这是正确的。只重新运行最后一条命令。

4. Publish to npm + MCP Registry 工作流会自动运行：它会使用出处证明执行 npm publish，轮询注册表直到 tarball 可用，然后通过 mcp-publisher 将对应的 server.json 推送到 MCP Registry。

如果该版本已发布到 npm，工作流会正常跳过 npm publish（用于处理部分由手动操作完成发布的版本的切换保护）。

npm 身份验证

发布使用 npm Trusted Publishing：工作流的 GitHub OIDC 令牌（id-token: write）会在运行时换取一次性发布令牌。仓库中无需保存 NPM_TOKEN 密钥。

绑定在 npm 网页界面中配置（package → Trusted Publishers）：provider 为 GitHub Actions，organization 为 lazyants，repository 为 transkribus-mcp-server，workflow 为 publish-registry.yml。

许可证

FSL-1.1-MIT — 完整条款请参阅 LICENSE。1.x 版本仍采用 MIT 许可证。