arabic-dict-mcp

An MCP server that gives AI agents grounded Arabic dictionary lookup — so replies about words, roots, and meanings come from real dictionary data instead of the model's parametric memory.

Built for Arabic learners who are tired of AI assistants confidently inventing meanings, roots, and derivations.

---

Why

Ask any LLM "what's the root of مكتوب and its siblings?" and you'll get an answer that sounds right — sometimes it is, often it isn't. This server exposes three tools the model can call to look words up in real dictionaries. When wired into Claude Code, Claude Desktop, or any MCP-compatible client, the model grounds its answer in the returned data instead of guessing.

Tools

Tool	What it does
lookup_root(root)	All dictionary entries under a root. Accepts any form: كتب, ك-ت-ب, كَتَبَ.
lookup_word(word)	Matches an inflected surface form or lemma. Returns each match's root so the agent can pivot to lookup_root for siblings.
search_meaning(query, lang="en"|"ar")	Full-text search over meanings for "what's the root for X?" style questions.

Diacritics. Input is tashkeel-insensitive — كَاتِبٌ, كاتب, and كَاتِب all match. Output preserves full vocalization from the source (including final case marks), because the vowelled form is what disambiguates the lemma.

Data sources

Downloaded at build time by scripts/build_dataset.py; not vendored in the repo.

Source	Coverage	License
linuxscout/arramooz	~40k MSA verb & noun entries — root, POS, wazn, forms, Arabic definitions	GPL
aliozdenisik/quran-arabic-roots-lane-lexicon	1,651 Quranic roots with English (Lane) glosses	GPLv3

Total: 5,610 roots · 42,351 entries in a unified SQLite index with FTS5.

Install

git clone https://github.com/arnizamani/arabic-dict-mcp.git
cd arabic-dict-mcp
uv venv .venv
uv pip install --python .venv/bin/python -e .
.venv/bin/python scripts/build_dataset.py    # ~40 MB download → data/arabic.db

Use — Claude Code / Desktop (stdio)

claude mcp add arabic-dict \
  -- /absolute/path/arabic-dict-mcp/.venv/bin/python -m arabic_dict_mcp.main

Or add to ~/.claude/mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "arabic-dict": {
      "command": "/absolute/path/arabic-dict-mcp/.venv/bin/python",
      "args": ["-m", "arabic_dict_mcp.main"]
    }
  }
}

Then ask Claude something like "What's the root of مكتوب and what other words come from it?" — the model will call lookup_word → lookup_root and reply with grounded data.

Use — HTTP (remote)

export MCP_AUTH_TOKEN=$(openssl rand -hex 24)
.venv/bin/python -m arabic_dict_mcp.main --http --host 0.0.0.0 --port 8000

Clients must send Authorization: Bearer $MCP_AUTH_TOKEN. The server refuses to start over HTTP without a token set.

Test

PYTHONPATH=src .venv/bin/python -m pytest tests/

Layout

src/arabic_dict_mcp/
  normalize.py   diacritic + letter-variant normalization (pyarabic)
  db.py          SQLite queries: lookup_root / lookup_word / search_meaning
  server.py      MCPServer with the three tools registered
  main.py        --http | stdio entrypoint
scripts/
  build_dataset.py   downloads sources → unified data/arabic.db with FTS5
tests/
  test_normalize.py

Known limits

• English meanings only cover the ~1,651 Quranic roots. Other MSA vocabulary returns terse Arabic glosses from arramooz only.
• arramooz definitions are short dictionary glosses, not full lexicon entries. A future version could bring in the full Lane's Lexicon (Perseus XML) for classical coverage.
• License asymmetry: this repository's code is MIT, but the downloaded dictionary data is GPL/GPLv3. Redistributing the built data/arabic.db triggers GPL; the code alone doesn't.

Contributing

Issues and pull requests are welcome. Ideas that would help:

• Full Lane's Lexicon ingestion beyond Quranic roots
• Additional MSA/dialect dictionaries with permissive licenses
• Root-similarity or fuzzy matching for typo tolerance

License

MIT — see LICENSE for details. Note the data-license asymmetry above.