Skip to main content
Glama
MazenAbbas

arabic-nlp-mcp

by MazenAbbas
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Arabic NLP MCP

An MCP v2 server centered on dependable Arabic preprocessing for search, RAG, and deduplication, with additional experimental linguistic tools. It uses typed, closed-world structured outputs. Results identify their method and expose ambiguity, fallback, or coverage rather than presenting heuristic scores as probabilities.

Tools

Tool

Behavior

Important boundary

arabic_normalize

Deterministic Unicode normalization

Options may be lossy; choose them for the downstream task

arabic_prepare_for_search

Profiles, mixed-language tokens, audit trail, and stable fingerprint

Primary supported workflow; search and aggressive profiles are explicitly lossy

arabic_detect_dialect

Weighted token/phrase evidence for Gulf, Egyptian, Levantine, and MSA

Heuristic; returns unknown or mixed when evidence is absent/ambiguous

arabic_sentiment

Explicit auto, transformer, or lexicon backend

Lexicon scores are not calibrated; transformer support is optional

arabic_diacritize

Lexical dictionary lookup with coverage report

Does not infer contextual grammar or case endings

The default MCP server exposes only the two stable preprocessing tools. The three linguistic tools are available through the deliberately named arabic-nlp-mcp-experimental entry point, so clients cannot mistake them for validated classifiers. All tools reject inputs over 20,000 characters and are annotated read-only, idempotent, non-destructive, and closed-world in MCP.

Related MCP server: mcp-arabic-toolkit

Install and run

Python 3.10 or newer is required.

python -m pip install .
arabic-nlp-mcp

To opt into the experimental dialect, sentiment, and lexical-diacritization tools, configure the command as arabic-nlp-mcp-experimental.

Transformer sentiment is intentionally not part of the lightweight core:

python -m pip install ".[transformers]"

Example MCP client configuration:

{
  "mcpServers": {
    "arabic-nlp": {
      "command": "python",
      "args": ["-m", "arabic_nlp_mcp.server"]
    }
  }
}

Python API

Functions return Pydantic models. Serialize with model_dump() when a plain dictionary is needed.

from arabic_nlp_mcp.dialect import detect_dialect
from arabic_nlp_mcp.search import prepare_for_search
from arabic_nlp_mcp.sentiment import analyze_sentiment

prepare_for_search("إِنَّ  AI رقم ١٢٣").model_dump()
detect_dialect("وين").model_dump()  # predicted: mixed
analyze_sentiment("مش حلو", backend="lexicon").model_dump()

backend="auto" attempts the transformer and reports fallback_reason if it uses the lexicon. backend="transformer" raises an error when unavailable; it never silently falls back.

Search profiles

  • conservative: compatibility normalization and invisible-format cleanup; preserves Arabic marks, letter variants, and digits.

  • search: additionally strips marks and unifies alef, yeh, Arabic/Persian digits, punctuation, and Latin case. This is the recommended default.

  • aggressive: additionally merges hamza seats and taa marbuta and collapses expressive repetition. Use only when recall matters more than false matches.

The original text is always returned. fingerprint is SHA-256 over normalized tokens, so equivalent search forms can be deduplicated without storing the normalized content as an identifier.

For streaming files without loading the corpus into memory:

arabic-nlp search --jsonl < input.txt > prepared.jsonl

Verification

python -m pip install -e ".[dev]"
ruff check .
pytest
python -m build
python -m twine check dist/*

The test corpus is a regression suite, not an external accuracy benchmark. This project publishes no accuracy, F1, or coverage claim until a licensed, versioned external dataset and reproducible evaluation are added.

Limitations

  • Dialect identification covers only four broad buckets and code-switching is not modeled. The evidence score is descriptive, not calibrated confidence.

  • Lexicon sentiment has limited vocabulary and basic local negation. The optional model has its own training-domain limitations.

  • Diacritization is useful only where dictionary coverage is adequate. It is not a replacement for a contextual morphological model.

  • Normalization can intentionally remove distinctions such as ى versus ي.

Do not use these heuristic outputs alone for high-stakes decisions.

arabic_prepare_for_search and arabic_normalize are the stable core. Dialect, sentiment, and lexical diacritization are labeled experimental until versioned external evaluations justify stronger guarantees.

Contributing and security

See CONTRIBUTING.md, SECURITY.md, and THREAT_MODEL.md. Changes are recorded in CHANGELOG.md. Released under the MIT License.

Available Tools

2 tools
arabic_normalizeC
Read-onlyIdempotent

Normalize Arabic text with individually controlled Unicode rules.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes
unify_yehNo
unify_alefNo
remove_tatweelNo
strip_diacriticsNo
unify_teh_marbutaNo
collapse_repeated_lettersNo
remove_control_charactersNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
lossyYes
methodNo
changedYes
originalYes
warningsNo
normalizedYes
transformations_appliedYes

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds only the vague notion that Unicode rules are individually controlled, which mostly restates the boolean flags in the schema rather than disclosing meaningful behavioral details like output shape or edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler words. It is efficiently worded, but the extreme brevity might underspecify a tool with 8 parameters; still, for pure conciseness it scores well.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 parameters, a visible sibling, and no schema-level descriptions), a one-sentence description is insufficient. It does not explain parameter choices, suggest when normalization is preferable to search preparation, or mention any behavior beyond the bare action, making the overall context incomplete despite annotations and output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate by explaining parameters, but it does not name or define any of the 8 properties. The phrase 'individually controlled Unicode rules' hints at the boolean toggles but provides no concrete meaning for 'unify_yeh', 'strip_diacritics', or the others, leaving the agent to rely on parameter names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Normalize') and resource ('Arabic text'), and the phrase 'individually controlled Unicode rules' signals that the tool applies configurable transformations. However, it does not differentiate this tool from its sibling 'arabic_prepare_for_search', so an agent cannot immediately tell which normalization-oriented tool to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool versus 'arabic_prepare_for_search', nor does it mention any exclusions or alternative tools. An agent would have to infer usage from the tool name and schema, which is insufficient for selecting between siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedarabic_normalize
    • First observedarabic_prepare_for_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored across 2 tools

Disambiguation4/5

The two tools have distinct purposes: one performs general normalization with controllable Unicode rules, while the other is specifically for preparing text for search/RAG/deduplication with richer output. There is some conceptual overlap since both involve normalization, but the names and descriptions clearly differentiate the more fundamental operation from the higher-level preparation pipeline.

Naming Consistency5/5

Both tool names follow a consistent 'arabic_<action>' snake_case pattern, with a clear verb indicating the operation. The prefix 'arabic_' also makes the domain obvious, and the naming style is uniform across the set.

Tool Count3/5

With only two tools, the server feels thin for a general Arabic NLP package. However, the two tools form a coherent pair that could be sufficient for a narrowly focused normalization and search-preparation use case.

Completeness3/5

The tools cover a normalization-to-search-preparation workflow with outputs like tokens, fingerprints, and audit trails, which addresses common RAG/deduplication needs. Missing are other typical Arabic NLP operations such as stemming, transliteration, named-entity recognition, or morphological analysis, leaving the server somewhat incomplete for a broader NLP scope.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • arabicfmt-mcp

    cc1a2b
    A
    license
    A
    quality
    A
    maintenance
    MCP server for correct Arabic formatting — currency, Hijri dates, number-to-words, RTL fixes and validation across all 22 Arab countries. Zero-dependency.
    17
    101 npm
    3
    MIT

  • mcp-arabic-toolkit

    BenjisCollector
    A
    license
    A
    quality
    D
    maintenance
    MCP server exposing Arabic text utilities: normalisation, tashkeel stripping, transliteration, heuristic dialect detection, and token counting.
    5
    MIT

  • Quranpedia MCP

    adelpro
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides AI clients with fast, hallucination-free access to the Quran through 13 MCP tools, covering search, navigation, morphology, tafsir, translations, and surah background over stdio and Streamable HTTP.
    MIT

  • mcp-claude-designer-arabic

    MarwanDevSpace
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides Arabic UI/UX design tools as an MCP server, offering RTL conversion, Arabic typography validation, cultural palettes, and anti-AI-slop auditing for AI-assisted design workflows.
    MIT