@verbumia/mcp

MCP server for Verbumia — wires Claude Desktop and other Model Context Protocol clients into your translation project.

This npm package bundles the Python MCP server source (no PyPI download). The launcher picks the best Python runtime on your host and runs the bundled verbumia_mcp directly.

Use it from Claude Desktop

{
  "mcpServers": {
    "verbumia": {
      "command": "npx",
      "args": ["-y", "@verbumia/mcp"],
      "env": {
        "VERBUMIA_API_KEY": "vrb_live_<prefix>.<secret>",
        "VERBUMIA_PROJECTS": "<project_uuid>",
        "VERBUMIA_BASE_URL": "https://api.verbumia.dev"
      }
    }
  }
}

For multiple projects (v0.11+), comma-separate the UUIDs in VERBUMIA_PROJECTS. The LLM then has to pass project_uuid on every tool call:

"env": {
  "VERBUMIA_API_KEY": "vrb_live_<prefix>.<secret>",
  "VERBUMIA_PROJECTS": "01993a..,01993b..,01993c.."
}

Restart Claude Desktop. All thirteen Verbumia tools (list_projects, get_project_info, list_keys, list_untranslated_keys, list_missing_keys, missing_keys_stats, acknowledge_missing_keys, create_key, propose_translation, publish_cdn, validate_translations, project_context_get, project_context_set) become callable from your prompt.

How the launcher works

The npm tarball ships the Python sources under python/ plus a pre-built wheel under python/dist/. The Node bin tries these in order:

1. uvx --from <bundled_wheel> verbumia-mcp — fastest, ephemeral venv. Recommended.
2. uv run --project <bundled_dir> verbumia-mcp — uv-managed, resolves deps from pyproject.toml.
3. pipx run --spec <bundled_wheel> verbumia-mcp — pipx-managed.
4. Ad-hoc venv at ~/.verbumia/mcp-venv-<wheelhash>/ — last-resort fallback that requires only python3 >= 3.12. Slow first run, fast thereafter.

Stdio is fully passthrough so the MCP JSON-RPC framing is preserved.

Environment variables (canonical)

| Var | Required | Default | Notes | |----------------------|----------|-----------------------------|--------------------------------------------------------| | VERBUMIA_API_KEY | yes | | Bearer ApiKey token. VERBUMIA_TOKEN accepted (back-compat) | | VERBUMIA_BASE_URL | no | https://api.verbumia.dev | Self-host / staging override. VERBUMIA_API_BASE accepted (back-compat) | | VERBUMIA_PROJECTS | no | (LLM picks per call) | CSV of project UUIDs. When >1, the LLM MUST pass project_uuid per call. | | VERBUMIA_PROJECT | no | (legacy) | Singular fallback for v0.10.x users. Ignored when VERBUMIA_PROJECTS is set (warns). |

Requirements

One of:

• uv (recommended, https://docs.astral.sh/uv/)
• pipx (https://pipx.pypa.io/)
• python3 >= 3.12 (for the venv fallback)

Self-check

npx -y @verbumia/mcp --self-check
# -> @verbumia/mcp launchers detected: uvx, uv, python3
# -> @verbumia/mcp bundled wheel: <node_modules>/.../python/dist/verbumia_mcp-…whl

License

MIT.