Parseur
Manage Parseur.com mailboxes, parser fields, documents, exports and webhooks.
Open source Open in the app JSON README (API)
About
Manage Parseur.com mailboxes, parser fields, documents, exports and webhooks.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- parseur
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.6.0
- Stars
- 7
- Forks
- 1
- Open pull requests
- 6
- Last push
- 2026-07-27T09:15:03Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:59
- Updated
- 2026-08-29 04:00:59
- Origin id
io.github.parseur/parseur-py
README
<!-- mcp-name: io.github.parseur/parseur-py -->
# 🤖🧙parseur-py
**parseur-py** is a modern Python client for the [Parseur](https://parseur.com) API.
It lets you **manage mailboxes, documents, uploads, and webhooks** programmatically or from the command line.
Built to help you automate document parsing at scale, parseur-py makes integrating with Parseur fast, easy, and Pythonic.
[](https://github.com/parseur/parseur-py)
[](https://badge.fury.io/py/parseur-py)
[](https://opensource.org/licenses/MIT)
[](https://parseur-py.readthedocs.io/en/latest/?badge=latest)
[](https://pepy.tech/projects/parseur-py)
---
## ✨ Features
✅ 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**.
These servers are **not affiliated with Parseur** and are **not covered** by Parseur’s [Privacy Policy](https://parseur.com/privacy) or [Data Processing Agreement](https://parseur.com/dpa).
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`):
```bash
PARSEUR_API_BASE=https://api.parseur.com \
PARSEUR_API_KEY=sk_your_key \
pytest tests/integration -v
```
---
### Initialize your configuration
Store your Parseur API credentials securely:
```bash
parseur init --api-key YOUR_PARSEUR_API_KEY
```
Your config is saved (by default) in:
```
~/.parseur.conf
```
---
### Example usage
List all your mailboxes:
```bash
parseur list-mailboxes
```
List documents in a mailbox:
```bash
parseur list-documents 12345
```
Upload a file to a mailbox (add `--wait` to block until it is parsed, with a live progress bar):
```bash
parseur upload-file 12345 ./path/to/document.pdf
parseur upload-file 12345 ./path/to/document.pdf --wait
```
Download a mailbox's results as a file (stdout by default, or `--output`):
```bash
parseur download-mailbox 12345 --format csv -o results.csv # whole mailbox
parseur list-parser-fields 12345 # find a table field id
parseur download-field 12345 PF951 --format xlsx -o lines.xlsx # a table field
```
Register a custom webhook:
```bash
parseur create-webhook --event document.processed --target-url https://yourserver.com/webhook --mailbox-id 12345
```
Listen to events in real time (requires [listener]):
```bash
parseur listen --event document.processed --mailbox-id 12345
```
With forwarding:
```bash
parseur listen --event document.processed --mailbox-id 12345 --redirect-url http://localhost --redirect-port 8000
```
---
## 📜 CLI Commands
Run:
```bash
parseur --help
```
for a full list of available commands.
### Highlights
- **init**: Set your API token and (optional) base URL
- **list-mailboxes**: Search and sort mailboxes
- **get-mailbox**: Fetch a mailbox by ID
- **get-mailbox-schema**: Get the mailbox parsing schema
- **list-parser-fields**: List the fields extracted by a mailbox
- **download-mailbox / download-field / download-export**: Download results as a file (csv/json/xlsx)
- **list-export-configs**: List a mailbox's custom export configurations
- **list-documents**: Advanced document search, filtering, sorting
- **get-document / get-document-logs**: Fetch document details and processing logs
- **reprocess-document / skip-document / copy-document / split-document / reverse-split-document / delete-document**: Document lifecycle operations
- **upload-file / upload-text**: Upload new documents (add `--wait` for synchronous parsing)
- **upload-folder**: Upload every file matching a glob path
- **create-webhook / get-webhook / list-webhooks / delete-webhook**: Create, get, list, and delete custom webhook integrations.
- **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](https://modelcontextprotocol.io) 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](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.
The full tool reference is in [MCP-TOOLS.md](MCP-TOOLS.md), and maintainer publishing instructions are in [MCP-PUBLISHING.md](MCP-PUBLISHING.md).
Quick zero-install command:
```bash
uvx --from "parseur-py[mcp]" parseur-py
```
---
## 🛠️ Configuration
Your API token and settings are stored in a simple INI file:
```
[parseur]
api_token = YOUR_API_KEY
base_url = https://api.parseur.com
```
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:
```python
parseur.Mailbox.list(api_key="sk_account_a")
parseur.Document.upload_file(123, "invoice.pdf", api_key="sk_account_b")
```
---
## 📖 Documentation
- [Parseur Official API Docs](https://help.parseur.com/en/articles/3566128-use-parseur-document-parsing-api)
- This package mirrors Parseur’s REST API, adding pagination handling, schema support, and convenient CLI commands.
---
## 💼 License
MIT License
---
## 🤝 Contributing
We welcome contributions! Please:
1. Fork the repo
2. Create your feature branch (`git checkout -b feature/foo`)
3. Commit your changes (`git commit -am 'Add foo'`)
4. Push to the branch (`git push origin feature/foo`)
5. Open a pull request
---
## ✨ Credits
Developed with ❤️ by the [Parseur](https://parseur.com) team.
---
*Parseur is the easiest way to automatically extract data from emails and documents. Stop copy-pasting data and automate your workflows!*