mcp-mistral-queue
This server provides a rate-limited, queue-based interface to the Mistral AI API, enabling safe multi-process and multi-client access to the Mistral free tier. It uses a shared SQLite database (WAL mode, stored in a secure per-user directory, path overridable) for coordination.
Key capabilities:
Single-shot prompts: Submit a plain text prompt for a text response.
Multi-turn conversations: Provide a full
messagesarray for context-aware interactions.Flexible model selection: Choose any Mistral chat model (default:
mistral-small-latest).Custom system prompt: Set a system prompt when using the single-prompt mode.
Priority queueing: Assign priority (1=high, 2=normal, 3=low) to influence processing order.
Automatic rate-limit handling: Enforces a ~31‑second start interval between requests and backs off on 429 errors, coordinating across processes.
Internal streaming & cancellation: Streams responses internally and handles client cancellation gracefully, updating the database on cancel.
MCP integration: Exposes an
ask_mistraltool for MCP-compatible clients (e.g., Claude Desktop, Vibe, Goose, OpenCode) and includes diagnostic commands (get_queue_status,clear_queue).CLI usage: Offers a direct command-line interface for ad‑hoc requests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-mistral-queue Explain Python list comprehensions briefly"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mistral-managed-queue
A CLI tool and MCP (Model Context Protocol) server that coordinates local and multi-process / multi-client calls to the Mistral free tier (~1 request / 30 seconds) via a shared SQLite queue. It uses SQLite (WAL mode) and async queueing with a single in-flight task to space request starts. This is best-effort traffic control, not an official SLA.
Package: mistral-managed-queue on PyPI · console script: mmq (not the package name) · current release: 0.2.2
Features
Automatic rate-limit coordination: Shared ~31s start interval; on 429, shared backoff then re-enter the gate. Resets to the base interval on success.
Multi-process & priority control: Multiple processes/tasks can enqueue work. Priority (default 2; larger value is processed first) plus single in-flight processing order the queue.
Flexible model & message options: Any Mistral chat model name (defaults to
mistral-small-latest; e.g.mistral-large-latest,codestral-latest).Streaming & cancel handling: Streams the Mistral API response internally (the tool returns the full text); on client cancel (
CancelledError) updates task status in the DB.Local control DB: Temp DB under a per-user directory with mode
0700(path overridable viaMMQ_TEMP_DB_PATH).PyPI / uvx: Install once or run ephemerally; entry point is
mmq.Catalog fetching (extras): Fetch provider model catalogs — see mmq/catalog/README.md.
Good free-tier fit: Occasional jobs (e.g. translating docs) that can wait ~31s between calls without burning a dedicated rate-limit stack.
Related MCP server: claude-sync
Prerequisites
Python 3.10+
uv recommended (
uvx/uv run);pipalso worksA Mistral API key (
MISTRAL_API_KEY)
export MISTRAL_API_KEY="your-mistral-api-key"Install (PyPI)
Published and verified on PyPI.
# One-shot (no permanent install) — recommended for MCP hosts
uvx --from mistral-managed-queue mmq --help
# Or install into an environment
uv pip install mistral-managed-queue
# pip install mistral-managed-queue
mmq --helpQuick smoke (needs MISTRAL_API_KEY; counts against free-tier quota):
uvx --from mistral-managed-queue mmq ask "Reply with pong only."Notes:
Console script name is
mmq. Wrong:uvx mistral-managed-queue .... Right:uvx --from mistral-managed-queue mmq ....Core dependencies:
mcp[cli]>=1.0.0,<2,mistralai>=1.0.0,<2. Catalog fetching needshttpxandPyYAML(install withpip install mistral-managed-queue[catalog]).
Usage
The CLI is subcommand-based: mmq ask, mmq fetch, mmq work, mmq purge. See also mmq catalog (extras) and mmq mcp (opt-in).
1. ask — direct API call (bypasses the queue)
Sends the prompt to the Mistral API immediately and prints the response.
# Basic run (default model: mistral-small-latest)
uvx --from mistral-managed-queue mmq ask "Explain Python list comprehensions briefly"
# or: mmq ask "Explain Python list comprehensions briefly"
# Choose a model (e.g. mistral-large-latest, codestral-latest)
mmq ask -m mistral-large-latest "Explain a complex algorithm"
# Custom system prompt
mmq ask -s "You are an AI that speaks casually." "How is the weather today?"
# JSON output for easy parsing
mmq ask -j "What is ownership in Rust?"2. fetch — enqueue for asynchronous processing
Registers the prompt in the shared queue. It is not processed here — run
mmq work to drain the queue.
# Enqueue with default priority (2)
mmq fetch "Summarize this document"
# Choose a model / system prompt / priority
mmq fetch -m mistral-large-latest -s "Be concise" -p 1 "Translate this to Japanese"Priority: larger value is processed first (ORDER BY priority DESC). Default is 2.
3. work — process the queue (worker mode)
Claims and processes pending tasks in priority order (highest first; FIFO within the same priority), each through the shared rate gate.
mmq work # drain all currently pending tasks
mmq work --once # process exactly one task and exit
mmq work --watch # keep processing new tasks until interrupted (Ctrl-C)4. purge — cancel queued tasks
mmq purge --pending # delete all pending tasks
mmq purge --all # delete every task (including completed/failed)
mmq purge --id 42 # delete a specific task by IDEnvironment variables (optional)
Variable | Default | Purpose |
| (required) | Mistral API key |
| per-user under tempdir | Shared queue DB file path |
|
| Seconds between starts (free-tier pacing) |
|
| Max backoff wait |
|
| Min sleep between retries |
|
| Backoff multiplier on 429 |
| off | Randomize base wait ( |
|
| Upper bound of randomized wait |
|
| Zombie task timeout (seconds) |
|
| Default model name |
| off | Enable MCP server — see mmq/README_MCP.md |
|
| Catalog fetch pacing — see mmq/catalog/README.md |
|
| Catalog fetch max backoff |
| off | Offline / e2e: fake client ( |
| — | Fixed fake response text (testing) |
| — |
|
With MMQ_RANDOM_INTERVAL=1, the base interval between API calls is drawn
uniformly from [MMQ_BASE_WAIT_TIME, MMQ_RANDOM_INTERVAL_MAX] (default
31–50 s) each time the gate resets, so the request cadence looks less
machine-like. 429 backoff is unaffected.
Control data location
The coordination temp DB is stored in a per-user directory created with mode 0700:
Default:
<tempdir>/mistral_managed_queue_<USER>/mistral_managed_flow_control.db
(tempfile.gettempdir(), often/tmpon Linux)Override: set
MMQ_TEMP_DB_PATHto a full file path (parent dir is created with0700)
Tests
# Unit + e2e (fake API; no network required)
uv run --with 'mcp[cli]>=1.0.0,<2' --with 'mistralai>=1.0.0,<2' \
--with pytest --with pytest-asyncio --no-project \
python -m pytest tests/ -v -m "not live"
# e2e only
uv run --with 'mcp[cli]>=1.0.0,<2' --with 'mistralai>=1.0.0,<2' \
--with pytest --with pytest-asyncio --no-project \
python -m pytest tests/e2e -v -m "not live"
# Live API (optional; consumes free-tier quota)
export MISTRAL_API_KEY=...
uv run --with 'mcp[cli]>=1.0.0,<2' --with 'mistralai>=1.0.0,<2' \
--with pytest --with pytest-asyncio --no-project \
python -m pytest tests/e2e/test_live_api.py -v -m livee2e uses MMQ_FAKE_API=1 and a short MMQ_BASE_WAIT_TIME to exercise process boundaries (CLI / MCP stdio).
For a manual Vibe UI check, see docs/SMOKE_VIBE.md.
Example: batch-style use of mmq (scripts/translate_readme.py)
Besides the CLI and MCP server, you can call the queue from Python. This repo ships a small sample:
scripts/translate_readme.py — regenerate locale READMEs from the English source via the same free-tier queue as mmq / ask_mistral.
Idea | Why it fits mmq |
Occasional job | Docs change far less often than chat traffic |
Can wait ~31s | ja then fr each take a gated slot |
Shared DB | Does not bypass other free-tier clients on the machine |
Programmatic API | Uses |
Locales workflow: edit the English sources (README.md, mmq/README_MCP.md, mmq/catalog/README.md); do not hand-maintain *.ja.md / *.fr.md.
export MISTRAL_API_KEY=...
# optional: TRANSLATE_MODEL=mistral-small-latest
# From a git checkout (imports the mmq package on PYTHONPATH via the script)
python scripts/translate_readme.py # all registered docs × ja + fr
python scripts/translate_readme.py --include README --lang ja
python scripts/translate_readme.py --dry-run # preview, no writeWhat the sample does:
Protects fenced code blocks (line FSM) and inline
codewith placeholdersEnqueues one translation job per language through
execute_mistral_queue_asyncRestores placeholders, fixes the language switcher, validates (e.g. balanced fences)
Writes outputs atomically
Use it as a template for other infrequent batch jobs (summaries, structured extraction) that should share the free-tier gate.
Acknowledgments
sioois for sharing information about the Mistral API free tier (link).
@fujibee for providing insights on using queues with SQLite WAL mode (#agmsg).
shunsuke_suzuki for the AI-friendly CLI development methodology (link).
Thank you all!
Further docs
mmq/README_MCP.md — MCP server setup and configuration
mmq/catalog/README.md — Catalog fetching (extras)
docs/SMOKE_VIBE.md — Vibe / MCP manual smoke
License
MIT License
Copyright (c) 2026 utenadev
Available Tools
1 toolask_mistralA
Mistral APIをキューイングとレートリミット制御付きで呼び出します。
Args: ctx: MCP Context (自動で渡されます) prompt: 単発の入力プロンプトテキスト messages: 会話履歴オブジェクトの配列 ([{"role": "...", "content": "..."}]) model: 利用する Mistral モデル名 (default: mistral-small-latest) system_prompt: カスタムシステムプロンプト (prompt 指定時のみ有効) priority: タスク優先度 (1: 高, 2: 通常, 3: 低)
Returns: Mistral API からのレスポンステキスト
Inputs: model, prompt, messages, priority, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
Only one tool exists, so there is no possibility of ambiguity between tools.
With a single tool, naming is trivially consistent; the name 'ask_mistral' follows a clear verb_noun convention.
A single tool for a queue-based system feels too minimal; typical queue management would require additional tools for status checking or cancellation.
The tool covers only the submission aspect; missing queue status, priority management, and cancellation capabilities create significant gaps.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for "taming the Claude" with structured task queues.1497 npm71MIT
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server that enables multiple Claude agents to coordinate through a shared message bus with SQLite persistence and real-time clock anchoring.MIT
- FlicenseNot gradedqualityDmaintenanceMCP server enabling natural-language querying of SQLite databases via schema discovery, GraphRAG retrieval, and safely guarded read-only SQL execution.-
- FlicenseNot gradedqualityDmaintenanceAn MCP server that provides an AI LLM orchestrator supporting multiple providers (LM Studio, Ollama, OpenAI, generic) plus SQLite-backed memory, kanban, and todo databases for persistent task and knowledge management.-