Metadata-Version: 2.4
Name: alqari-mcp
Version: 1.0.0
Summary: Official MCP server for AlQari, the Arabic and English document intelligence platform
Author-email: VoltStack <dev@voltstack.tech>
License-Expression: MIT
Project-URL: Homepage, https://alqari.sa
Keywords: mcp,ocr,document-intelligence,arabic,alqari,qari
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<3,>=2.3
Requires-Dist: httpx<1.0,>=0.25
Requires-Dist: pydantic<3.0,>=2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# AlQari MCP Server

[![PyPI](https://img.shields.io/pypi/v/alqari-mcp)](https://pypi.org/project/alqari-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/alqari-mcp)](https://pypi.org/project/alqari-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/licenses/MIT)

The official [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **[AlQari](https://alqari.sa)**, the document intelligence platform for Arabic and English documents.

Connect AlQari to Claude, ChatGPT, Codex, Cursor or any other MCP-compatible assistant, and work with your company's documents in plain language:

> *"OCR this invoice and extract the invoice number, VAT number and total."*
>
> *"Find last month's Acme Trading contracts and summarize their payment terms."*
>
> *"Check this invoice: VAT must be 15% of the subtotal and the supplier VAT number must be present."*

## Features

- **OCR** for PDFs and images in Arabic, English or both
- **Search** your company's documents by the words, names, numbers and dates inside them
- **Ask, summarize, extract fields and tables, classify and validate** any document
- **Run your AlQari workflows** on local files and read their results
- **Usage reporting:** every billed result reports the credits it used and the balance left

## Requirements

- Python 3.10 or newer
- An AlQari company account, and an API key created by a company Admin
- An MCP-compatible app, such as Claude Desktop, Claude Code, the ChatGPT desktop app, Codex or Cursor

## Quick start

### 1. Create an API key

1. Sign in at [alqari.sa](https://alqari.sa) with an **Admin** account.
2. Open **Settings → API Keys** ([direct link](https://alqari.sa/dashboard/settings?tab=api-keys)).
3. Under **Create new key**, enter a name such as `AI assistant` and click **Create**.
4. Click **Copy**, store the key somewhere safe, then click **I've saved my key**.

The key starts with `qari_` and is shown only once. If you don't see the **API Keys** tab, ask your company's AlQari Admin for a key.

### 2. Install

```bash
pip install alqari-mcp
```

This installs the `alqari-mcp` command. Desktop apps often don't share your terminal's `PATH`, so note its full path:

```bash
where alqari-mcp    # Windows
which alqari-mcp    # macOS / Linux
```

### 3. Connect your app

Replace `qari_your_api_key` below with your own key.

<details open>
<summary><b>Claude Desktop</b></summary>

Open **Settings → Developer → Edit Config** and add the server to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "alqari": {
      "command": "C:\\path\\to\\alqari-mcp.exe",
      "env": {
        "ALQARI_API_KEY": "qari_your_api_key"
      }
    }
  }
}
```

Set `command` to the full path from step 2. On Windows, write each backslash twice, as shown. Restart Claude Desktop, and the AlQari tools appear in the chat's tools menu.

</details>

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport stdio alqari --env ALQARI_API_KEY=qari_your_api_key -- alqari-mcp
```

Run `/mcp` inside Claude Code to check the connection.

</details>

<details>
<summary><b>ChatGPT desktop app and Codex</b></summary>

The ChatGPT desktop app, the Codex CLI and the Codex IDE extension share one MCP configuration. Either run:

```bash
codex mcp add alqari --env ALQARI_API_KEY=qari_your_api_key -- alqari-mcp
```

or add this to `~/.codex/config.toml`:

```toml
[mcp_servers.alqari]
command = "alqari-mcp"    # or the full path from step 2
tool_timeout_sec = 300

[mcp_servers.alqari.env]
ALQARI_API_KEY = "qari_your_api_key"
```

Codex stops a tool after 60 seconds by default, so raise `tool_timeout_sec`: OCR of long PDFs and workflow runs can take longer.

</details>

<details>
<summary><b>Cursor</b></summary>

Add the same `mcpServers` block shown for Claude Desktop to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project).

</details>

<details>
<summary><b>Other MCP apps</b></summary>

Any app that supports local (stdio) MCP servers can run AlQari. Set the command to `alqari-mcp` (or its full path) and the environment variable `ALQARI_API_KEY` to your key.

</details>

> **Web and mobile apps:** ChatGPT and Claude on the web and on mobile can only connect to MCP servers hosted on the internet, so they can't run this local server. Use a desktop app or a coding tool instead.

## Tools

| Tool | What it does |
|---|---|
| `search_documents` | Find documents by the words, names, numbers or dates in them |
| `list_documents` | List documents, filtered by file name, status or type |
| `get_document_text` | Read a document's stored OCR text, in chunks |
| `upload_and_ocr` | Upload a local PDF or image and extract its text |
| `ask_document` | Ask a question and get an answer based on the document |
| `summarize_document` | Summarize a document as a brief, bullet points, sections or a narrative |
| `extract_fields` | Extract named fields, such as invoice number or total, as structured data |
| `extract_tables` | Extract tables as rows and columns |
| `classify_document` | Identify the document type, optionally from your own list of labels |
| `validate_document` | Check a document against rules written in plain language |
| `list_workflows` | List your company's AlQari workflows |
| `run_workflow` | Run an "Upload Document" workflow on local files |
| `get_workflow_run` | Check a workflow run's status, results and cost |

Uploads accept `.pdf`, `.png`, `.jpg`, `.jpeg`, `.tif`, `.tiff` and `.webp` files, given by their full path.

## Billing

Billed tools are charged to the AlQari company that owns the API key, at the same credit prices as the AlQari web app and API.

- Each billed result includes `credits_consumed` and `remaining_credits`. Workflow runs report a `billing` breakdown instead. Your assistant can tell you what each action cost.
- A call is refused before any work starts if the company is out of credits, its subscription or trial has ended, or it has an overdue invoice. The error message explains which.
- Work that has already run, such as OCR of an uploaded file, is charged in full, even if this takes the company past its remaining credits.
- Every charge appears in your company's AlQari usage history.

## Configuration

| Environment variable | Required | Default | Description |
|---|---|---|---|
| `ALQARI_API_KEY` | Yes | |
| `ALQARI_TIMEOUT` | No | `300` |
| `ALQARI_BASE_URL` | No | `https://api.alqari.sa` |

## Security

- **Protect your API key.** It gives access to all of your company's documents and credits. Keep it out of shared files and source control. If a key leaks, click **Revoke** next to it on the **API Keys** tab and create a new one. Each person should have their own key, so one can be revoked without affecting the others.
- **Runs on your computer.** The server is a small local program that your AI app starts. It talks only to the AlQari API, over HTTPS, and keeps no copies of your documents.
- **Uploads are limited to documents.** Only PDF and image files can be uploaded. Other files, such as `.env` files or private keys, are refused before they are read.
- **Billed tools are marked.** Free tools carry MCP's read-only hint and billed tools don't, so apps that support tool hints can ask you before a call that spends credits.
- **Document content is treated as data.** The assistant is told never to follow instructions written inside a document.

## Troubleshooting

| Problem | What to do |
|---|---|
| The AlQari tools don't appear | Use the full path to `alqari-mcp` in your app's config, then fully restart the app. |
| `HTTP 401` |
| `HTTP 402` |
| A tool times out | Long PDFs and workflow runs can take minutes. Raise your app's tool timeout, and `ALQARI_TIMEOUT` if needed. |
| `run_workflow` returns runs in `still_running` |

To test the server without an AI app, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which requires Node.js:

```bash
npx @modelcontextprotocol/inspector -e ALQARI_API_KEY=qari_your_api_key alqari-mcp
```

## License

Released under the [MIT License](https://opensource.org/licenses/MIT).
