# transkribus-mcp-server

[![Tests](https://github.com/lazyants/transkribus-mcp-server/actions/workflows/test.yml/badge.svg)](https://github.com/lazyants/transkribus-mcp-server/actions/workflows/test.yml)

MCP server for the [Transkribus REST API](https://transkribus.eu/). 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](https://api-staging.transkribus.org/v2/openapi.json) names a staging server; production v2 availability has not been confirmed. Both backends take `config.textRecognition.htrId`.

## Installation

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

Or run directly:

```bash
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:

```bash
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
`<account>.<service>` — `user.transkribus-mcp` and `password.transkribus-mcp`
for the default service — which is exactly what the server reads back:

```powershell
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'
```

> 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
> `<account>.<service>`.

#### Linux

```bash
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

```bash
export TRANSKRIBUS_USER=your-email@example.com
export TRANSKRIBUS_PASSWORD=your-password
```

Or, with a session you already hold:

```bash
export TRANSKRIBUS_SESSION_ID=your-session-id
```

### Environment variables

| Variable | Default | Description |
| --- | --- | --- |
| `TRANSKRIBUS_USER` | — | Account e-mail; used when the keyring has no `user` entry for the configured service |
| `TRANSKRIBUS_PASSWORD` | — | Account password; used when the keyring has no `password` entry |
| `TRANSKRIBUS_SESSION_ID` | — | An existing session id; used when the keyring has no `session-id` entry |
| `TRANSKRIBUS_KEYRING_SERVICE` | `transkribus-mcp` | Keyring service name. Override to connect to several Transkribus accounts at once — run one server instance per account, each with its own service name |

### 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:

```bash
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`.

| Backend | Job identifiers | Terminal statuses | Result retention | Tools |
|---|---|---|---|---|
| `v1` (default) | Positive integers, including numeric strings | `FINISHED`, `FAILED` | Two days | Submit, status, PAGE XML, ALTO XML |
| `v2` (beta, staging) | Positive integers, numeric strings, UUIDs | `FINISHED`, `FAILED`, `CANCELLED` | 24 hours after completion | The same four tools, plus longpoll and ZIP |

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](https://docs.transkribus.org/processing/how-jobs-work)
describes lifecycle, links, and retention; the [compatibility guide](https://docs.transkribus.org/compatibility)
documents the Developer Platform's existing `/v2/processes` contract.

## Entry Points

| Command | Domains | Tools |
|---|---|---|
| `transkribus-mcp-server` | All 23 domains | 304 (306 with v2) |
| `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 — no legacy auth tools | 4 (6 with v2) |

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:

1. `transkribus_upload_create_structure` — give it `collId`, a `title`, and a `pages` array of
   `{ fileName, pageNr }` (one entry per page image you are about to send). Returns an upload with
   an `uploadId`.
2. `transkribus_upload_page` — call once per page with the `uploadId` and `imagePath` (a path to a
   local image file), optionally `pageXmlPath` for an existing PAGE XML transcript.
3. `transkribus_upload_get_status` — poll with the `uploadId` until 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`. PDF ingestion is not supported; convert the PDF to
page images first and use the flow above.

## 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:

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

Or use split servers (pick the splits you need):

```json
{
  "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"]
    }
  }
}
```

Two Transkribus accounts at once — one instance per account, each pointed at its
own keyring service name:

```json
{
  "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" }
    }
  }
}
```

Without a keyring, pass the credentials in `env` instead:

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

## Claude Desktop

Add to `claude_desktop_config.json`. With the credentials in the OS keyring
(recommended — assumes the default service name `transkribus-mcp`):

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

Without a keyring:

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

## Security

- **Use the OS keyring** to keep your password out of config files and shell history entirely (see [Configuration](#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:

1. Bump the version in `package.json`, `package-lock.json`, and `server.json` (`npm version <x.y.z> --no-git-tag-version` updates the first two together). `npm run check-versions` **hard-fails** unless `package.json#/version` and `server.json#/packages[0].version` agree. `server.json#/version` is checked loosely: it must be present, and it only fails when it *regresses* below `packages[0].version` — a value left behind at the previous release passes with a `WARN:` line and exit 0. The script does **not** look at `package-lock.json` or `CHANGELOG.md` at all, so read its output rather than trusting its exit code.
2. Update `CHANGELOG.md`.
3. Commit, and **merge the version bump to `main` before creating the release**. Then create the tag yourself, on a SHA you have checked, and only then create the release from it:

   ```bash
   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"
   ```

   **The failure this prevents:** with no existing tag, `gh release create vX.Y.Z` places 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's `package.json`, producing a `vX.Y.Z` GitHub Release that silently republishes the old version. The publish workflow now refuses to continue when `GITHUB_REF_NAME` is not `v<package.json version>`, so that exact scenario fails before `npm publish` rather 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.oid`** names the release PR's own squash commit. Do not substitute `git rev-parse origin/main`: that is merely whatever sits on `main` at the moment you look, so an unrelated merge landing in the gap gets tagged and shipped instead. `gh` exits 0 and prints nothing for an unmerged PR, hence the explicit `test -n`.
   - **The `&&` chain** stops at the first failure instead of falling through to the irreversible step. Both `git show` calls 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 unless `pipefail` is set, which is not assumed here.
   - **`git merge-base --is-ancestor`** proves the commit is reachable from `main`. 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.json` out of the target commit**, not the working tree — which would still show the right version while `$SHA` pointed elsewhere.
   - **The `awk`** lifts that version's section out of the commit's `CHANGELOG.md` for `--notes-file`. Without it the release body is whatever `--notes-from-tag` finds in the annotation — here the literal string `vX.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 -q` rather than `test -s` guards the result: a section empty apart from its blank line still produces a one-byte file, which `test -s` accepts.
   - **`--verify-tag`** makes `gh` abort 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 create` fails after the tag is already pushed, do not rerun the whole block; it will stop at `git tag`, which is correct. Rerun only the final command.
4. The `Publish to npm + MCP Registry` workflow runs automatically: it `npm publish`es with provenance, polls the registry until the tarball is available, then pushes the matching `server.json` to the MCP Registry via `mcp-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](LICENSE) — see [LICENSE](LICENSE) for the full terms. Versions `1.x` remain MIT-licensed.