verbumia-mcp 0.12.1

Model Context Protocol server for Verbumia — list projects, missing keys, propose translations from Claude Desktop and other MCP clients.

Verbumia MCP server

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

Status

Thirteen tools wired: 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.

Project context document (V1.2)

project_context_get / project_context_set read and write a free-form markdown blob attached to the project — terminology, brand voice, domain notes (religious, legal, medical, gaming, etc.). The content is intended as ambient context for human translators and for AI agents producing translations: prepend it to your translation prompts so every output stays consistent with the project's vocabulary and tone. Hard cap 100 KiB.

Scopes:

• project_context_get requires project:read (existing scope).
• project_context_set requires project:settings:write (new scope, narrower than project:write since settings changes propagate to every translator's prompt context).

Note: the blanket mcp:* scope is not sufficient for these tools — grant the precise scope on the key.

Install

# Recommended (zero-install, used by Claude Desktop's mcp.json):
npx -y @verbumia/mcp

# Or from PyPI:
pipx install verbumia-mcp

A Homebrew tap (brew install verbumia/tap/verbumia-mcp) is coming once we publish to npm.

Configure (Claude Desktop)

Open Settings → Developer → Edit Config, then:

Single-project setup:

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

Multi-project setup (v0.11+) — comma-separate the UUIDs and Claude will pass project_uuid on each tool call:

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

Restart Claude Desktop. Tools show up in the prompt UI.

Environment

Variable	Required	Default	Description
VERBUMIA_API_KEY	yes		API key from Org Settings → API Keys (VERBUMIA_TOKEN also accepted, back-compat)
VERBUMIA_PROJECTS	no	(LLM passes per call)	CSV of project UUIDs. When >1, the LLM MUST pass project_uuid on each tool call.
VERBUMIA_PROJECT	no	(legacy)	Singular fallback for v0.10.x users. Ignored when VERBUMIA_PROJECTS is set (warns).
VERBUMIA_BASE_URL	no	https://api.verbumia.dev	Override for self-host or staging (VERBUMIA_API_BASE also accepted, back-compat)

The token format is vrb_live_<prefix>.<secret> and must carry the mcp:* scope. For the project_context_* tools, also grant project:read and/or project:settings:write — see the Project context document section above. Treat the token like any other secret — keychain or .env, never commit.

If your API key is pinned to a single project (its project_uuid is set server-side), listing additional UUIDs in VERBUMIA_PROJECTS will surface as a 403 API key is scoped to a different project from the backend on any call targeting one of the others.

Local development

cd mcp
uv sync
uv run verbumia-mcp        # stdio transport — pipe MCP frames over stdin/stdout

License

MIT.