@verbumia/mcp

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

• uvx --from <bundled_wheel> verbumia-mcp — fastest, ephemeral venv. Recommended.
• uv run --project <bundled_dir> verbumia-mcp — uv-managed, resolves deps from pyproject.toml.
• pipx run --spec <bundled_wheel> verbumia-mcp — pipx-managed.
• 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.