Voro MCP

An MCP server for working with the Võro language: local dictionary and corpus lookup, GiellaLT-backed analysis/spellcheck/grammar tools, and Neurotõlge translation.

What it's for

This MCP server gives language models practical tools for working with the Võro language. Võro is a lower-resource language, so general-purpose language models may make more mistakes with it than with widely supported languages such as English, or even Estonian.

By connecting the model to dictionaries, corpus search, morphological analysis, spellchecking, grammar checking, translation, and form generation, this server helps improve the model’s ability to understand, generate, correct, and translate Võro text.

It can be useful for tasks such as Võro translation, checking and improving generated text, exploring real usage examples, generating word forms, detecting unknown words, and supporting people who are learning or working with the Võro language.

Install

Quick setup

On Debian/Ubuntu, one command does the whole setup.

make setup        # scripts/run_local_ubuntu.sh; see `make help` for every task

You need make, Python, and the usual shell tools installed first. The setup target installs the HFST/Divvun system binaries (adding the Apertium package repo first if your system can't already find divvun-gramcheck), downloads the SQLite datasets and the prebuilt Giella models, creates .venv, and installs the package. Smoke-test it with make test.

make test runs straight from the checkout (no install needed). Tests that need the SQLite datasets or the Giella tools skip with a hint when those aren't present, so a bare clone still reports green — run make data and make giella (or the full make setup) to actually exercise them.

1. System binaries the Giella tools shell out to: hfst-optimized-lookup, hfst-ospell, cg3, divvun-checker. On Debian/Ubuntu they come from the Apertium nightly apt repo:

   curl -fsSL https://apertium.projectjj.com/apt/install-nightly.sh | sudo bash
   sudo apt-get install -y hfst hfst-ospell cg3 divvun-gramcheck perl gawk bash
   

2. The package, into a virtualenv (make install):

   python3 -m venv .venv
   . .venv/bin/activate
   pip install -e .
   

3. Data and models, they are pulled from GitHub releases:

   scripts/fetch_data.sh
   scripts/fetch_giella.sh
   

4. Verify the external tools resolved (prints JSON and exits):

   vro-mcp-check
   

From least to most system-wide. Do the steps that apply, from the repo root.

1. Client registration — unregister the server from whichever MCP client you added it to:

   claude mcp remove vro    # Claude Code
   codex mcp remove vro     # Codex CLI
   

2. Local install — delete the virtualenv:

   rm -rf .venv
   

3. Downloads — the SQLite datasets and Giella models (large; re-fetchable with make data / make giella):

   rm -rf data                 # SQLite datasets + the data/giella-share models
   rm -rf .cache/giella-build  # only if you built Giella from source
   rm -f .env                  # only if you created one for deployment
   

   To drop the code too, delete the directory you cloned into.

4. The Apertium/Divvun apt repo — only if make setup added it (it skips this when divvun-gramcheck was already installable). Find the source it dropped and remove it:

   ls /etc/apt/sources.list.d/ | grep -i apertium
   sudo rm -f /etc/apt/sources.list.d/apertium*.list
   sudo apt-get update
   

5. System packages — remove only the Võro-specific binaries. Leave shared tools (python3, git, make, perl, gawk, …) in place, since other software may depend on them:

   sudo apt-get remove hfst hfst-ospell cg3 divvun-gramcheck
   sudo apt-get autoremove        # optional: drop now-unused dependencies
   

Tools

Most lookup tools accept a single word or a list for batched queries. Successful tool outputs are intentionally compact so MCP clients spend less context on internal IDs, debug metadata, and provenance fields.

Resources

Markdown references are exposed over MCP:

• vro://grammar/noun-cases: noun/adjective/numeral/pronoun declension.
• vro://grammar/verb-conjugation: verb conjugation, moods, tenses, voice.
• vro://grammar/orthography-and-standard: writing system (alphabet, glottal stop q, palatalization, high õ, length and negation spelling) and Võro Institute standard-language orientation.
• vro://guide/translator-prompt: translator/post-editor prompt and workflow for producing Võro text with these tools.

Configuration

The data lives under data/ and is fetched for you. make setup (or make data + make giella) downloads everything, so you normally configure nothing. The fetch scripts honour VRO_DATA_REPO, VRO_DATA_TAG, and VRO_GIELLA_TAG to point at a different release.

All path defaults are repo-local; override them with environment variables when needed. For Modal deploy defaults, copy .env.example to .env.

Translation backend resilience

translate_vro is intentionally an HTTP client, not a bundled translation engine. The default points at the public Neurotõlge/TartuNLP endpoint, but you can point VRO_NEUROTOLGE_BASE_URL at a compatible local or self-hosted backend. See TartuNLP's translation-api and translation-worker repositories for their setup instructions.

Connect a client

All a client needs is the binary's absolute path. Run make local-url to print that path and ready-to-paste config for Claude Code and Codex.

Claude Code:

claude mcp add vro -- /absolute/path/to/vro-mcp-server/.venv/bin/vro-mcp-server

Codex:

codex mcp add vro -- /absolute/path/to/vro-mcp-server/.venv/bin/vro-mcp-server

Generic JSON MCP client configuration:

{
  "mcpServers": {
    "vro": {
      "command": "/absolute/path/to/vro-mcp-server/.venv/bin/vro-mcp-server",
      "cwd": "/absolute/path/to/vro-mcp-server"
    }
  }
}

Deployment

The local setup above runs the server on your own machine. To use it from anywhere — including the Claude and ChatGPT web apps — deploy it to Modal instead.

make deploy

This builds the server in Modal's cloud and prints a hosted HTTPS endpoint like:

https://<workspace>--vro-mcp-serve.modal.run/<secret>/mcp

Paste that URL into any MCP client (Claude Code, Codex, Claude web, ChatGPT) and you can reach the tools from anywhere, no local install needed. The server wakes on demand and sits idle for free between requests. The URL embeds a random secret path that acts as its password, so keep it private.

See DEPLOY.md for prerequisites, connecting each client, and the full set of deploy commands.

License

Code is MIT (LICENSE). The SQLite datasets are CC-BY-SA-4.0 and the prebuilt GiellaLT models are GPL-3.0. Both are distributed as separate release assets, each bundling its own license and attribution. See NOTICE.md for scope and source summaries.