MistralDocAI MCP Server

An MCP server that converts documents and images to Markdown using Mistral AI's OCR and vision models. Point it at a PDF, a slide deck, a Word document, or a scanned image, and your MCP client gets Markdown back.

It is for people who already use an MCP client such as Claude Desktop and want document conversion inside it, rather than as a separate tool.

Status: actively maintained, best-effort, as a personal project. Version 2.0 is current. See Versioning and compatibility before upgrading from 1.x.

Language: this project is English-only. Interface text, documentation, and error messages are English, and no localized builds are published. Documents you process may be in any language Mistral's models support.

Requirements

| | | |---|---| | Node.js | 22 or later, declared in engines.node in package.json | | Python | 3.10 or later, on your PATH as python3 or python | | Mistral API key | Free to create at console.mistral.ai | | Platforms | Linux, macOS, and Windows, all covered by CI |

You do not install the Python dependencies yourself. The server creates a virtual environment under ~/.mistraldocai-mcp/ on first run.

Install

Verify that your machine can run it:

npx @trsdn/mistraldocai-mcp-server --test

That creates the Python environment, installs the dependencies, imports the server, and reports what it found. Run it before configuring a client, because it turns a silent client-side failure into a readable error.

Configure

Your API key

Either export it in the environment your client launches the server from:

export MISTRAL_API_KEY=your_key_here

Or put it in ~/.mistraldocai-mcp/.env, which the server seeds on first run:

MISTRAL_API_KEY=your_key_here

The file is usually the more reliable option, because desktop MCP clients often do not inherit your shell environment.

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "mistraldocai": {
      "command": "npx",
      "args": ["@trsdn/mistraldocai-mcp-server"],
      "env": {
        "MISTRAL_API_KEY": "your_key_here"
      }
    }
  }
}

Other clients

Any client that launches an MCP server over stdio works. Use npx @trsdn/mistraldocai-mcp-server as the command and provide MISTRAL_API_KEY in the environment.

Tools

process_document

Converts one document or image to Markdown. Give it either a path or base64 content.

| Parameter | Type | Notes | |---|---|---| | file_path | string | Path to the file. Use this or base64_content. | | base64_content | string | File content, base64 encoded. Requires file_name. | | file_name | string | Original file name, used to determine the format. | | mime_type | string | Optional. Inferred from the extension when omitted. |

{ "name": "process_document", "arguments": { "file_path": "/path/to/report.pdf" } }

process_directory

Converts every supported file in a directory, writing one .md file per input and preserving the directory structure.

| Parameter | Type | Notes | |---|---|---| | input_directory | string | Directory to read. | | output_directory | string | Directory to write Markdown into. |

get_supported_formats

Returns the supported formats and their limits. Takes no parameters.

Supported formats

| Kind | Extensions | |---|---| | Documents | .pdf, .pptx, .docx | | Images | .png, .jpg, .jpeg, .gif, .bmp, .avif |

Limits are set by Mistral's OCR API: 50 MB per file and 1,000 pages per document. Pricing and throughput are Mistral's, not this project's; check their pricing page for current figures rather than trusting a number copied into a README.

Data and privacy

Documents you process are sent to Mistral AI. This is the entire point of the server, but it means the content leaves your machine. Do not process material you are not permitted to share with a third-party AI provider.

| Question | Answer | |---|---| | What is collected | Nothing by this project. It has no telemetry, no analytics, and no crash reporting. | | Where data goes | api.mistral.ai, to convert your document. That is the only outbound destination, other than PyPI and npm during installation. | | Who receives your content | Mistral AI. Their privacy policy governs what they do with it. | | What is stored locally | ~/.mistraldocai-mcp/.env holds your API key. ~/.mistraldocai-mcp/venv/ holds the Python environment. Converted Markdown goes wherever you asked for it. | | Retention | This project keeps nothing beyond those files. Delete ~/.mistraldocai-mcp/ to remove everything it created. Retention at Mistral is governed by their terms. | | Logging | Diagnostics go to stderr and never include your API key or document content. |

Accessibility

Console output is plain ASCII with no colour and no decorative symbols, so it stays readable in a screen reader, in a Windows terminal, and in a client log that strips formatting.

Known limitation: the server has no interface of its own. Everything you see comes from your MCP client, so keyboard access, focus handling, and contrast are your client's behaviour, not this project's. Accessibility problems in the conversation view belong in your client's issue tracker.

Versioning and compatibility

This project follows Semantic Versioning. A major version is where the Node floor rises, the Python mcp dependency crosses a major, or a tool's contract changes.

Upgrading from 1.x requires Node.js 22 or later. Version 1.0.4 and earlier cannot be installed from a clean environment at all: their Python requirements were unbounded and now resolve to incompatible releases. There is no supported 1.x fallback. The full account is in CHANGELOG.md.

How it works

MCP client  --stdio-->  dist/index.js  --spawn-->  python/mcp_server.py  --HTTPS-->  api.mistral.ai
                             |                            |
                    manages ~/.mistraldocai-mcp/    docmistral.py does the
                    venv, deps, and .env            conversion

Two constraints explain most of the design:

• stdout is the protocol. The MCP client parses stdout as JSON-RPC, so every diagnostic in both languages goes to stderr. A stray print corrupts the session.
• The package directory is read-only. A global npm install cannot be written to, so the virtual environment, the .env, and all other state live under ~/.mistraldocai-mcp/.

Development

git clone https://github.com/trsdn/MistralDocAI-mcp.git
cd MistralDocAI-mcp
npm ci
npm run build

Validate a change with the single command that CI also runs:

npm run verify

If you changed anything under python/, also run ruff check . and python3 scripts/verify_python_server.py against an interpreter that has python/mcp_requirements.txt installed.

AGENTS.md holds the full layout, conventions, and the list of operations that are off limits. It is written for AI agents, and it is the fastest orientation for a human too.

Project documents

| Document | What it covers | |---|---| | CHANGELOG.md | What changed in each release, and upgrade concerns | | CONTRIBUTING.md | Setup, validation, and what gets a pull request sent back | | AGENTS.md | Repository layout, conventions, and forbidden operations | | SECURITY.md | Supported versions and private vulnerability reporting | | SUPPORT.md | Common problems and where to ask | | docs/self-assessment.md | Conformance against the repository quality standard |

License

MIT.

This repository is assessed against the trsdn Repository Quality Standard. The result is recorded in .github/conformance.yml, with per-criterion evidence in docs/self-assessment.md.