Skip to main content
Glama
README.md
<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

A3.6/5.0

Scored across 19 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count4/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues