transkribus-mcp-server

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

301 tools across 22 resource domains, with 8 entry points so you can pick the right server for your MCP client's tool limit.

API scope: This server covers the legacy Transkribus TrpServer REST API. The newer Processing API v2 (OIDC auth, /processing/v2, account.readcoop.eu) is intentionally out of scope.

Installation

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

Or run directly:

npx @lazyants/transkribus-mcp-server

Configuration

Transkribus uses session-based authentication. You can authenticate in two ways:

Option 1: Username + Password (auto-login)

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

The server will automatically log in and manage the session.

Option 2: Direct session ID

export TRANSKRIBUS_SESSION_ID=your-session-id

Use this if you already have a valid session from the Transkribus platform.

Entry Points

Command	Domains	Tools
transkribus-mcp-server	All 22 domains	301
transkribus-mcp-collections	Auth, Collections (core/docs/pages/users/crowd/editdecl/credits/stats/labels/activity/tags)	133
transkribus-mcp-admin	Auth, Admin, Credits, Uploads, Labels, Files, System, Root	63
transkribus-mcp-transcription	Auth, Recognition, Layout Analysis, PyLaia, P2PaLA, DU	48
transkribus-mcp-users	Auth, Users, Crowdsourcing, eLearning	30
transkribus-mcp-models	Auth, Models	27
transkribus-mcp-jobs	Auth, Jobs, Actions	19
transkribus-mcp-search	Auth, Search, KWS	17

Use split servers to reduce context size — pick only the splits you need.

Claude Code

Add to ~/.claude/settings.json:

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

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

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

Claude Desktop

Add to claude_desktop_config.json:

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

Security

• Never commit your credentials to version control
• Use environment variables or a .env file (excluded via .gitignore)
• Session IDs expire — prefer username/password for long-running setups

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 and server.json (npm run check-versions enforces alignment between package.json#/version and server.json#/packages[0].version).
2. Update CHANGELOG.md.
3. Commit, then gh release create vX.Y.Z --notes-from-tag (or write release notes inline).
4. The Publish to npm + MCP Registry workflow runs automatically: it npm publishes 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 — see LICENSE for the full terms. Versions 1.x remain MIT-licensed.