transkribus

transkribus-mcp-server

Transkribus REST API 用の MCP サーバーです。Model Context Protocol を通じて、コレクション、ドキュメント、HTR/OCR による認識、モデルなどを管理できます。

デフォルトで 304 個のツール、Processing v2 を有効にすると 306 個のツールを、23 のリソースドメインにわたって提供します。MCP クライアントのツール上限に合わせて適切なサーバーを選べるよう、9 つのエントリーポイントを用意しています。

**API の対象範囲：**このサーバーは Transkribus の 2 つの API に対応しています。

• 従来の TrpServer REST API（https://transkribus.eu/TrpServer/rest）。セッションベースで、300 個のツールに対応します。
• Processing API。account.readcoop.eu を介した OIDC ベアラー認証で、デフォルトの Metagrapho v1 バックエンド（https://transkribus.eu/processing/v1）では transkribus_processing_* ツールを 4 個、オプションの Developer Platform v2 ベータ版（https://api-staging.transkribus.org/v2）では 6 個利用できます。

v2 を使うには、明示的な選択が必要です。公開されている OpenAPI にはステージングサーバーが記載されていますが、本番環境で v2 が利用できるかは確認されていません。どちらのバックエンドも config.textRecognition.htrId を使用します。

インストール

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

または、直接実行します。

npx @lazyants/transkribus-mcp-server

設定

Transkribus では、セッションベースの認証を使用します。認証情報は値ごとに次の優先順で取得されます。

1. OS のキーチェーン（推奨。設定ファイルに平文で書き込まれることはありません）
2. 環境変数（TRANSKRIBUS_USER と TRANSKRIBUS_PASSWORD、または TRANSKRIBUS_SESSION_ID）

ユーザー名とパスワードを使用すると、サーバーがログインしてセッションを管理します。すでに取得済みのセッション ID も使用できます。両方を設定した場合はセッション ID が優先されますが、セッション ID には有効期限があります。そのため、長期運用ではユーザー名とパスワードの使用をおすすめします。これにより、401 エラー後にサーバーが再認証できます。

キーチェーンは必須ではありません。利用できない場合（Secret Service がないヘッドレス Linux マシン、未対応のプラットフォーム、--omit=optional を指定したインストールなど）、または 5 秒以内に応答がない場合、サーバーは環境変数にフォールバックします。

OS のキーチェーンに認証情報を保存する

デフォルトでは、1 つのサービス名 transkribus-mcp の下に 3 つの項目を登録します。項目は user、password、session-id です（使用する項目だけを保存してください）。

重要

以下のコマンドは、値を引数として受け取るのではなく、対話形式のプロンプトから読み取ります。そのため、値がシェルの履歴やコマンドライン、別のプロセスの起動環境に残ることはありません。パスワードをコマンドラインに直接貼り付けないでください。

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   # キーチェーンモジュールはこのパッケージに含まれています
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 アカウントに同時に接続する場合は上書きしてください。アカウントごとにサービス名を変えて、サーバーインスタンスを1つずつ起動します

Processing API の認証情報

transkribus_processing_* ツールは異なる認証方式を使用する別のサービスと通信しますが、追加の設定は不要です。同じ TRANSKRIBUS_USER と TRANSKRIBUS_PASSWORD を OIDC ベアラートークン（READCOOP SSO パスワードグラント、クライアント processing-api-client）と交換し、自動的に更新します。TRANSKRIBUS_SESSION_ID は適用されません。

任意で指定できる上書き設定は2つあります。

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

オプションの処理 v2 ベータ

起動前に、MCP サーバーの環境に TRANSKRIBUS_PROCESSING_BACKEND=v2 を設定してください。デフォルトは v1 です。無効な値を設定すると、構成エラーになります。v2 では、文書化されているステージングホスト https://api-staging.transkribus.org/v2 を使用し、v1 と同じ OIDC 認証情報と PAGE/ALTO XML 操作を利用します。この選択は、フルサーバーと transkribus-mcp-processing の両方にある Processing ツールに適用されます。

バックエンド	ジョブ識別子	終了ステータス	結果の保持期間	ツール
v1（デフォルト）	数値文字列を含む正の整数	FINISHED、FAILED	2 日間	送信、ステータス、PAGE XML、ALTO XML
v2（ベータ、ステージング）	正の整数、数値文字列、UUID	FINISHED、FAILED、CANCELLED	完了から24時間	同じ4つのツールに加えて、longpoll と ZIP

v2 の送信結果とステータス結果では、API フィールドが保持され、terminal、pollingAvailable、linksByRel が追加されます。リンクは、self、status、longpoll、result、page-result などの安定した rel 値でインデックス化されます。表示タイトルは動作に影響しません。longpoll 関係が存在しない場合はポーリングができなくなり、終了状態では常にポーリングが停止します。リンク URL はデータとして返されます。サーバーがリクエストするのは、選択されたバックエンドで文書化されているパスのみです。

• transkribus_processing_longpoll：processId を渡し、必要に応じて interval（ミリ秒単位の int32 数値）を指定します。呼び出しは、観測されたジョブを timedOut: false とともに返します。HTTP 200 でも終了前のステータス変更が含まれる場合があるため、terminal を確認してください。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 は、結果を取得できないことを意味します。

これら2つのツールは、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）

コンテキストサイズを抑えるには、分割サーバーを使用し、必要なものだけを選んでください。

ドキュメントのアップロード

ドキュメントを取り込むには、次の3つの手順に従います。

1. transkribus_upload_create_structure — collId、title、および送信するページ画像ごとに1つの { fileName, pageNr } を含む pages 配列を指定します。uploadId を含むアップロード情報が返されます。
2. transkribus_upload_page — 各ページについて1回ずつ呼び出し、uploadId と imagePath（ローカル画像ファイルへのパス）を指定します。既存の PAGE XML の転写データがある場合は、pageXmlPath も指定できます。
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"]
    }
  }
}

2つの Transkribus アカウントを同時に使用する場合は、アカウントごとに1つのインスタンスを用意し、それぞれ別のキーチェーンサービス名を指定します。

{
  "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 のキーチェーンを使用して、パスワードが設定ファイルやシェルの履歴に残らないようにしてください（設定を参照）。
• 認証情報をバージョン管理にコミットしないでください。
• セッション 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 を実行すると、最初の2つが同時に更新されます）。npm run check-versions は、package.json#/version と server.json#/packages[0].version が一致しない場合、必ず失敗します。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 から見つかったバージョンを公開し、古いバージョンを気づかれないまま再公開する vX.Y.Z の GitHub Release が作成されます。現在、公開ワークフローは GITHUB_REF_NAME が v<package.json version> と一致しない場合、処理を続行しません。そのため、このシナリオでは気づかれないまま再公開するのではなく、npm publish の前に失敗します。上記の手順は引き続き必須であり、ワークフローでは防げないケースも保護します。ワークフローのチェックはリリースが作成された後にのみ実行され、正しいバージョンを含むコミットであれば通過するため、誤ったタグは検出しますが、誤ったコミットへのタグ付けは検出できません。

   各要素は不可欠です。

   • gh pr view … .mergeCommit.oid は、リリース PR 自体のスカッシュコミットを示します。git rev-parse origin/main に置き換えないでください。これは確認時点で main にあるコミットにすぎないため、その間に無関係なマージが入ると、それがタグ付けされてリリースされてしまいます。マージされていない PR に対して gh は終了コード 0 で何も出力しないため、明示的に test -n を実行しています。
   • && の連鎖により、最初の失敗時点で処理が止まり、取り消せない手順に進むことを防ぎます。2 つの git show 呼び出しはパイプに直接つなぐのではなく、変数に代入しているため、終了ステータスが確実にチェックされます。pipefail が設定されていない限り、パイプラインで報告されるのは最後のコマンドのステータスだけです。ここでは pipefail が設定されていることを前提としていません。
   • git merge-base --is-ancestor により、そのコミットが main から到達可能であることを確認します。コミットが存在するだけでは不十分です。別のブランチをフェッチしたことでローカルに存在している場合もあり、バージョンファイルがたまたま一致していると、残りのチェックをすべて通過してしまう可能性があります。
   • バージョンテストは、作業ツリーではなく対象コミットから package.json を読み取ります。作業ツリーから読み取ると、$SHA が別のコミットを指していても正しいバージョンが表示されてしまいます。
   • awk は、--notes-file 用に、そのバージョンのセクションをコミットの CHANGELOG.md から取り出します。これを行わない場合、リリース本文には --notes-from-tag が注釈から取得する内容が使われます。この場合は文字列 vX.Y.Z そのもので、どのバージョンのリリースノートとしても不適切であり、破壊的変更を含むリリースでは誤解を招きます。次の ## [ 見出し、または最初のリンク参照定義のいずれかで処理を止めます。最も古いエントリの後には見出しがなく、そのままではリンク参照ブロック全体を取り込んでしまうためです。結果の確認に test -s ではなく grep -q を使います。空行だけのセクションでも 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 の Web UI（パッケージ → Trusted Publishers）で設定されています。プロバイダーは GitHub Actions、組織は lazyants、リポジトリは transkribus-mcp-server、ワークフローは publish-registry.yml です。

ライセンス

FSL-1.1-MIT — 全条件については LICENSE を参照してください。バージョン 1.x は引き続き MIT ライセンスです。