ethioMCP
<div align="center">
<h1><code>ethioMCP</code></h1>
<p><strong>An MCP server that extends LLMs such as Claude and ChatGPT with Ethiopian linguistic resources.</strong></p>
<p>
<img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="python">
<img src="https://img.shields.io/badge/MCP-2.x-purple" alt="mcp">
<img src="https://img.shields.io/badge/license-MIT-green" alt="license">
</p>
</div>
## About
LLMs are weak at the morphology and lexicon of Ethiopian and Eritrean languages.
ethioMCP gives them tools backed by established linguistic repositories. Each
repository is a **connector**, and adding a new one is a single folder (see
[docs/adding-a-connector.md](docs/adding-a-connector.md)).
## Connectors
### `hornmorpho`: [hltdi/HornMorpho](https://github.com/hltdi/HornMorpho)
License: GPL-3.0. It runs as a separate process.
| Tool | What it does |
|---|---|
| `hornmorpho_analyze` | Analyzes a word: lemma, root, POS, segmentation, UD features, UniMorph tags, transliteration, morphemes |
| `hornmorpho_analyze_sentence` | Analyzes a tokenized sentence and returns CoNLL-U |
| `hornmorpho_generate` | Generates word forms from a root (`ስብር`) or a lemma (`ሰበረ`), with features |
| `hornmorpho_phonetic` | Transliteration that shows gemination and epenthetic vowels |
| `hornmorpho_languages` | Supported languages: `am`, `ti`, `om`, `tig` |
### `geezorg`: [geezorg/data](https://github.com/geezorg/data)
License: CC BY-SA 4.0.
| Tool | What it does |
|---|---|
| `geezorg_lookup` | Dictionary search in either direction: Amharic (NMSU-Say, Science & Technology), Tigrinya and Ge'ez (Kidane Wolde Kifle) |
| `geezorg_verb_paradigm` | Armbruster Amharic verb tables: perfect, imperfect, jussive, gerund, and the other forms |
| `geezorg_place_names` | Ethiopian toponyms |
| `geezorg_corpus_search` | Keyword-in-context search of the POS-tagged WIC Amharic news corpus |
| `geezorg_list_datasets`, `geezorg_browse`, `geezorg_read_file` | Explore the rest of the archive |
### `afrim`: [fodydev/afrim-data](https://github.com/fodydev/afrim-data)
The Ethiopic input methods of the [afrim](https://github.com/pythonbrad/afrim)
IME. License: none specified upstream.
| Tool | What it does |
|---|---|
| `afrim_transliterate` | Romanised keyboard input to Ge'ez script (`aityoPya` → ኢትዮጵያ), with layouts `am`, `gez`, `ethiopic`, `geezime`; words found in the Amharic wordlist are flagged |
| `afrim_keystrokes` | Ge'ez script to the keystrokes that type it |
| `afrim_lookup` | Spelling check in a ~340k-form Amharic wordlist and an Ethiopian names list (no glosses) |
| `afrim_geez_numeral` | Integers to Ge'ez numerals (1966 → ፲፱፻፷፮) |
| `afrim_ethiopian_date` | Gregorian ↔ Ethiopian calendar, with Amharic month names |
| `afrim_list_schemes` | The layouts and their word lists |
`ethiomcp_connectors` lists the connectors and whether each one is ready.
## Install
```bash
git clone <this repo> && cd ethioMCP
uv sync
uv run ethiomcp setup # all connectors (HornMorpho: am,ti,om)
uv run ethiomcp setup hornmorpho -o langs=am
uv run ethiomcp setup afrim -o path=../afrim-data # use a local clone instead of GitHub
uv run ethiomcp doctor
```
Downloaded data goes to a per-user cache directory, not to the project:
`~/.cache/ethiomcp` on Linux, `~/Library/Caches/ethiomcp` on macOS, and
`%LOCALAPPDATA%\ethiomcp\Cache` on Windows. Set `ETHIOMCP_DATA_DIR` to use
another location.
Connectors that need their own Python environment get a venv inside that
folder, with the Python version they declare. For example, HornMorpho runs on
Python < 3.13, whatever version the server uses. `uv` downloads the
interpreter if needed.
## Use it
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"ethiomcp": {
"command": "uv",
"args": ["--directory", "/path/to/ethioMCP", "run", "ethiomcp", "serve"]
}
}
}
```
**Claude Code:**
```bash
claude mcp add ethiomcp -- uv --directory /path/to/ethioMCP run ethiomcp serve
```
**ChatGPT** (developer mode or custom connectors) needs an HTTP endpoint:
```bash
uv run ethiomcp serve --transport streamable-http --host 0.0.0.0 --port 8000
# expose https://<host>/mcp, e.g. with a reverse proxy or tunnel
```
To enable only some connectors: `ETHIOMCP_CONNECTORS=geezorg uv run ethiomcp serve`.
> The first HornMorpho call in a session loads the language model (~20–60 s).
> Later calls are fast, because the worker stays alive.
## Development
```bash
uv run ruff check && uv run ruff format --check
uv run pytest # unit tests, no network
uv run pytest -m integration # real data (run `ethiomcp setup` first)
npx @modelcontextprotocol/inspector uv run ethiomcp serve
```
## License
The ethioMCP code is MIT. Each connector's data and libraries keep their
upstream license, which is reported with every tool result. HornMorpho (GPL-3.0)
is never imported into the server process.
TDQS
Scored across 19 tools
Most tools have clearly distinct purposes across the afrim, geezorg, and hornmorpho connectors. Some potential confusion exists between afrim_lookup and geezorg_lookup, and between geezorg_verb_paradigm and hornmorpho_generate, but the descriptions clarify dataset and operation differences.
Tool names consistently use snake_case with connector prefixes (afrim_, geezorg_, hornmorpho_, ethiomcp_), which makes grouping predictable. Most names follow a verb/noun operation pattern, though a few list-style tools are noun phrases rather than verb-led.
The 19 tools are spread across four distinct connectors, so the count is broad but reasonable for a multi-domain Ethiopian language toolkit. Each tool appears to serve a specific operation rather than duplicating another.
The surface covers transliteration, keyboard mapping, dictionary lookup, morphology analysis/generation, corpus search, dates, numerals, and archive browsing/reading. Minor gaps exist, such as no write/update operations for archive files and no translation or audio features, but core workflows are well covered.