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.

Related MCP server: word-orb

Tools

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.

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

Optional: Hans Wehr (personal use)

The classic Hans Wehr Arabic–English Dictionary has full entries with principal parts (past + present + maṣdar) inline — e.g. kataba u (katb, كتبة kitba, كتابة kitāba) to write, …. Passing --hanswehr to the builder adds ~25k Hans Wehr entries.

.venv/bin/python scripts/build_dataset.py --hanswehr

The underlying dictionary is copyrighted (Otto Harrassowitz / Spoken Language Services). The transcription downloaded lives in GibreelAbdullah/HansWehrDictionary and ships without a license file. Use of --hanswehr is at your own discretion for personal use only — this repo does not ship the data, does not commit it, and does not encourage redistributing the resulting data/arabic.db.

If you already have a copy locally, point the flag at it:

.venv/bin/python scripts/build_dataset.py --hanswehr /path/to/hanswehr.sqlite

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.

From a Windows client, server in WSL

Point command at wsl.exe and give the interpreter its Linux path:

{
  "mcpServers": {
    "arabic-dict": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "/mnt/c/path/to/arabic-dict-mcp/.venv/bin/python",
        "-m",
        "arabic_dict_mcp.main"
      ]
    }
  }
}

If the client reports ClosedResourceError, the pipe to the server died rather than a tool failing — usually the WSL VM cold-starting past the client's startup timeout. Run any wsl.exe echo hi first to warm the VM, then retry.

Debug — MCP Inspector

The server is a silent stdio daemon: it prints nothing on startup and waits for newline-delimited JSON-RPC on stdin. To poke at it interactively, use the MCP Inspector rather than running it bare.

npx @modelcontextprotocol/inspector .venv/bin/python -m arabic_dict_mcp.main

Open the URL it prints — it carries a pre-filled session token, and the bare http://localhost:6274 will fail auth. Then Connect → Tools → List Tools.

Against a git worktree (where data/ is gitignored and absent), point at the source and a real database:

PYTHONPATH=$PWD/src \
ARABIC_MCP_DB=/path/to/arabic-dict-mcp/data/arabic.db \
npx @modelcontextprotocol/inspector \
  /path/to/arabic-dict-mcp/.venv/bin/python -m arabic_dict_mcp.main

From Windows, mirror whatever the client uses so the same wsl.exe hop is exercised:

npx @modelcontextprotocol/inspector wsl.exe -e /mnt/c/path/to/arabic-dict-mcp/.venv/bin/python -m arabic_dict_mcp.main

For HTTP mode, start the server yourself, then launch a bare npx @modelcontextprotocol/inspector and connect to http://127.0.0.1:8000/mcp with transport Streamable HTTP.

Driving stdio by hand

No inspector needed — pipe the handshake in, but keep stdin open. On EOF the server shuts down, so a plain heredoc answers initialize and then exits before later replies arrive; the trailing sleep is what makes them show up.

{ printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"lookup_root","arguments":{"root":"كتب"}}}'
  sleep 5
} | .venv/bin/python -m arabic_dict_mcp.main

Order matters: initialize, then the initialized notification, then real calls. Note that stdout is protocol-only — any stray print() in server code corrupts the framing and the client drops the connection, so logs must go to stderr.

Use — HTTP (remote)

.venv/bin/python -m arabic_dict_mcp.main --http --port 8000

By default, HTTP is unauthenticated — fine for localhost testing. For anything on the public network, set a bearer token first:

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

When MCP_AUTH_TOKEN is set, clients must send Authorization: Bearer $MCP_AUTH_TOKEN.

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.