Manage Parseur.com mailboxes, parser fields, documents, exports and webhooks.
io.github.parseur/parseur-py (MCP Server)
This MCP server provides programmatic access to Parseur by way of parseur-py. It supports managing Parseur mailboxes, parser fields, documents, uploads, and exports, and it includes webhook capabilities. It can be used from Python or via the command line to automate document parsing workflows.
🛠️ Key Features
Manage mailboxes
Manage parser fields
Manage documents
Manage uploads and exports
Webhooks support
🚀 Use Cases
Automate document parsing at scale
Programmatically integrate with Parseur for mailbox and document handling
Trigger or respond to parsing events via webhooks
Use command-line tooling for batch or scripted operations
⚡ Developer Benefits
Modern Python client for the Parseur API
Supports both Python and command line usage
⚠️ Limitations
Server data does not specify authentication, configuration, or supported environments.
✅ List, search, and sort mailboxes
✅ Get mailbox details and schema
✅ List, search, filter, and sort documents
✅ Upload documents by file or email content
✅ Reprocess, skip, copy, or delete documents
✅ Manage custom webhooks for real-time events
✅ Listen to events in real time with a temporary webhook & tunnel
✅ Fully-featured Command Line Interface (CLI)
✅ Built-in MCP server to drive Parseur from AI assistants (Claude, Cursor, …)
⚠️ Disclaimer about Localtunnel
When using the parseur listen command (with event listener support), your data is forwarded through localtunnel servers.
Data transmitted through localtunnel is not encrypted end-to-end.
➡️ Use this feature at your own risk.
For production-grade setups, we strongly recommend configuring your own secure webhook endpoint instead of relying on localtunnel.
🚀 Quick Start
Install the package
bash
pip install parseur-py
With event listener support (Flask + localtunnel)
bash
pip install "parseur-py[listener]"
With MCP server support (use Parseur from AI assistants)
bash
pip install "parseur-py[mcp]"
Install the package from source
bash
pip install -e .
Build documentation
bash
pip install -r requirements-doc.txt
cd docs
make html
Run the tests
Unit tests run fully offline:
bash
pytest
Integration tests hit the real Parseur API. They create and delete real
resources, so they're skipped unless credentials are provided via the
environment (never committed or stored in ~/.parseur.conf):
enable-webhook / pause-webhook: Activate or pause a webhook for a specific mailbox.
listen: Create a temporary webhook and listen to events in real time (with optional redirect & silent mode)
mcp: Run the Parseur MCP server so AI assistants can manage your account (requires [mcp])
🔎 Advanced Search & Filtering
Mailbox listing supports:
Search by name or email prefix
Sort by:
name
document_count
template_count
PARSEDOK_count (processed)
PARSEDKO_count (failed)
QUOTAEXC_count (quota exceeded)
EXPORTKO_count (export failed)
Document listing supports:
Search in:
document ID
document name
template name
email addresses (from, to, cc, bcc)
document metadata header
Sort by:
name
created (received date)
processed date
status
Filter by:
received_after / received_before dates
Include parsed result in response
⚡ Webhooks Support
Easily register custom webhooks for events like:
document.processed
document.processed.flattened
document.template_needed
document.export_failed
table.processed
table.processed.flattened
Your webhook endpoint will receive POST notifications with Parseur payloads, enabling real-time integrations with your systems.
🤖 MCP Server (AI assistants)
parseur-py ships an MCP server that exposes Parseur as tools any MCP-compatible AI assistant (Claude Desktop, Codex, Cursor, Claude Code, and others) can call directly.
Start with MCP.md if you want to connect Parseur to Claude, Codex, or Cursor. It separates the recommended user setup from the developer setup and includes copy-paste configs for each client.
You can customize the path by setting `--config-path` in your calls if needed.
🐍 Python Client Usage
Beyond the CLI, parseur-py is a standard Python library. Example:
python
import parseur
parseur.api_key = "YOUR_API_KEY"for mailbox in parseur.Mailbox.list():
print(mailbox.name)
Per-call API key override
Every method accepts an optional api_key argument that takes priority over
the global parseur.api_key for that single call — useful for multi-account
or multi-tenant code:
