{
  "markdown": "<!-- mcp-name: io.github.parseur/parseur-py -->\n\n# 🤖🧙parseur-py\n\n**parseur-py** is a modern Python client for the [Parseur](https://parseur.com) API.\n\nIt lets you **manage mailboxes, documents, uploads, and webhooks** programmatically or from the command line.\n\nBuilt to help you automate document parsing at scale, parseur-py makes integrating with Parseur fast, easy, and Pythonic.\n\n[![GitHub Repo](https://img.shields.io/badge/GitHub-parseur--py-blue?logo=github)](https://github.com/parseur/parseur-py)\n[![PyPI version](https://badge.fury.io/py/parseur-py.svg)](https://badge.fury.io/py/parseur-py)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Read the Docs](https://readthedocs.org/projects/parseur-py/badge/?version=latest)](https://parseur-py.readthedocs.io/en/latest/?badge=latest)\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/parseur-py?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=BLUE&left_text=users)](https://pepy.tech/projects/parseur-py)\n\n---\n\n## ✨ Features\n\n✅ List, search, and sort mailboxes  \n✅ Get mailbox details and schema  \n✅ List, search, filter, and sort documents  \n✅ Upload documents by file or email content  \n✅ Reprocess, skip, copy, or delete documents  \n✅ Manage custom webhooks for real-time events  \n✅ Listen to events in real time with a temporary webhook & tunnel  \n✅ Fully-featured **Command Line Interface (CLI)**  \n✅ Built-in **MCP server** to drive Parseur from AI assistants (Claude, Cursor, …)\n\n---\n\n## ⚠️ Disclaimer about Localtunnel\n\nWhen using the `parseur listen` command (with event listener support), your data is forwarded through **localtunnel servers**.\n\nThese 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).\n\nData transmitted through localtunnel is **not encrypted end-to-end**.\n\n➡️ **Use this feature at your own risk.**\n\nFor production-grade setups, we strongly recommend configuring your own secure webhook endpoint instead of relying on localtunnel.\n\n---\n\n## 🚀 Quick Start\n\n### Install the package\n\n```bash\npip install parseur-py\n```\n\nWith event listener support (Flask + localtunnel)\n\n```bash\npip install \"parseur-py[listener]\"\n```\n\nWith MCP server support (use Parseur from AI assistants)\n\n```bash\npip install \"parseur-py[mcp]\"\n```\n\n### Install the package from source\n\n```bash\npip install -e .\n```\n\n### Build documentation\n\n```bash\npip install -r requirements-doc.txt\ncd docs\nmake html\n```\n\n### Run the tests\n\nUnit tests run fully offline:\n\n```bash\npytest\n```\n\nIntegration tests hit the real Parseur API. They create and delete real\nresources, so they're skipped unless credentials are provided **via the\nenvironment** (never committed or stored in `~/.parseur.conf`):\n\n```bash\nPARSEUR_API_BASE=https://api.parseur.com \\\nPARSEUR_API_KEY=sk_your_key \\\npytest tests/integration -v\n```\n\n---\n\n### Initialize your configuration\n\nStore your Parseur API credentials securely:\n\n```bash\nparseur init --api-key YOUR_PARSEUR_API_KEY\n```\n\nYour config is saved (by default) in:\n\n```\n~/.parseur.conf\n```\n\n---\n\n### Example usage\n\nList all your mailboxes:\n\n```bash\nparseur list-mailboxes\n```\n\nList documents in a mailbox:\n\n```bash\nparseur list-documents 12345\n```\n\nUpload a file to a mailbox (add `--wait` to block until it is parsed, with a live progress bar):\n\n```bash\nparseur upload-file 12345 ./path/to/document.pdf\nparseur upload-file 12345 ./path/to/document.pdf --wait\n```\n\nDownload a mailbox's results as a file (stdout by default, or `--output`):\n\n```bash\nparseur download-mailbox 12345 --format csv -o results.csv     # whole mailbox\nparseur list-parser-fields 12345                               # find a table field id\nparseur download-field 12345 PF951 --format xlsx -o lines.xlsx  # a table field\n```\n\nRegister a custom webhook:\n\n```bash\nparseur create-webhook --event document.processed --target-url https://yourserver.com/webhook --mailbox-id 12345\n```\n\nListen to events in real time (requires [listener]):\n\n```bash\nparseur listen --event document.processed --mailbox-id 12345\n```\n\nWith forwarding:\n\n```bash\nparseur listen --event document.processed --mailbox-id 12345 --redirect-url http://localhost --redirect-port 8000\n```\n\n---\n\n## 📜 CLI Commands\n\nRun:\n\n```bash\nparseur --help\n```\n\nfor a full list of available commands.\n\n### Highlights\n\n- **init**: Set your API token and (optional) base URL  \n- **list-mailboxes**: Search and sort mailboxes  \n- **get-mailbox**: Fetch a mailbox by ID  \n- **get-mailbox-schema**: Get the mailbox parsing schema  \n- **list-parser-fields**: List the fields extracted by a mailbox  \n- **download-mailbox / download-field / download-export**: Download results as a file (csv/json/xlsx)  \n- **list-export-configs**: List a mailbox's custom export configurations  \n- **list-documents**: Advanced document search, filtering, sorting  \n- **get-document / get-document-logs**: Fetch document details and processing logs  \n- **reprocess-document / skip-document / copy-document / split-document / reverse-split-document / delete-document**: Document lifecycle operations  \n- **upload-file / upload-text**: Upload new documents (add `--wait` for synchronous parsing)  \n- **upload-folder**: Upload every file matching a glob path  \n- **create-webhook / get-webhook / list-webhooks / delete-webhook**: Create, get, list, and delete custom webhook integrations.\n- **enable-webhook / pause-webhook**: Activate or pause a webhook for a specific mailbox.\n- **listen**: Create a temporary webhook and listen to events in real time (with optional redirect & silent mode)\n- **mcp**: Run the Parseur MCP server so AI assistants can manage your account (requires `[mcp]`)\n\n---\n\n## 🔎 Advanced Search & Filtering\n\n**Mailbox listing supports:**\n\n- **Search** by name or email prefix\n- **Sort** by:\n  - name\n  - document_count\n  - template_count\n  - PARSEDOK_count (processed)\n  - PARSEDKO_count (failed)\n  - QUOTAEXC_count (quota exceeded)\n  - EXPORTKO_count (export failed)\n\n**Document listing supports:**\n\n- **Search** in:\n  - document ID\n  - document name\n  - template name\n  - email addresses (from, to, cc, bcc)\n  - document metadata header\n- **Sort** by:\n  - name\n  - created (received date)\n  - processed date\n  - status\n- **Filter** by:\n  - received_after / received_before dates\n- **Include** parsed result in response\n\n---\n\n## ⚡ Webhooks Support\n\nEasily register custom webhooks for events like:\n\n- `document.processed`\n- `document.processed.flattened`\n- `document.template_needed`\n- `document.export_failed`\n- `table.processed`\n- `table.processed.flattened`\n\nYour webhook endpoint will receive POST notifications with Parseur payloads, enabling real-time integrations with your systems.\n\n---\n\n## 🤖 MCP Server (AI assistants)\n\n**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.\n\nStart 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.\n\nThe full tool reference is in [MCP-TOOLS.md](MCP-TOOLS.md), and maintainer publishing instructions are in [MCP-PUBLISHING.md](MCP-PUBLISHING.md).\n\nQuick zero-install command:\n\n```bash\nuvx --from \"parseur-py[mcp]\" parseur-py\n```\n\n---\n\n## 🛠️ Configuration\n\nYour API token and settings are stored in a simple INI file:\n\n```\n[parseur]\napi_token = YOUR_API_KEY\nbase_url = https://api.parseur.com\n```\n\nYou can customize the path by setting \\`--config-path\\` in your calls if needed.\n\n---\n\n## 🐍 Python Client Usage\n\nBeyond the CLI, **parseur-py** is a standard Python library. Example:\n\n```python\nimport parseur\n\nparseur.api_key = \"YOUR_API_KEY\"\n\nfor mailbox in parseur.Mailbox.list():\n    print(mailbox.name)\n```\n\n### Per-call API key override\n\nEvery method accepts an optional `api_key` argument that **takes priority over\nthe global `parseur.api_key`** for that single call — useful for multi-account\nor multi-tenant code:\n\n```python\nparseur.Mailbox.list(api_key=\"sk_account_a\")\nparseur.Document.upload_file(123, \"invoice.pdf\", api_key=\"sk_account_b\")\n```\n\n---\n\n## 📖 Documentation\n\n- [Parseur Official API Docs](https://help.parseur.com/en/articles/3566128-use-parseur-document-parsing-api)\n- This package mirrors Parseur’s REST API, adding pagination handling, schema support, and convenient CLI commands.\n\n---\n\n## 💼 License\n\nMIT License\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please:\n\n1. Fork the repo\n2. Create your feature branch (`git checkout -b feature/foo`)\n3. Commit your changes (`git commit -am 'Add foo'`)\n4. Push to the branch (`git push origin feature/foo`)\n5. Open a pull request\n\n---\n\n## ✨ Credits\n\nDeveloped with ❤️ by the [Parseur](https://parseur.com) team.\n\n---\n\n*Parseur is the easiest way to automatically extract data from emails and documents. Stop copy-pasting data and automate your workflows!*\n",
  "bytes": 9101,
  "sha": "444bce8a639f1ce4de9ea86bea1273bbab311ff3a6a18b65d3914d271906ba57",
  "repo_slug": "parseur/parseur-py",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_parseur_parseur_py_910f2a9b/readme"
}