<div align="center">
<picture>
<img alt="Omni-LPR Logo" src="logo.svg" width="300">
</picture>
<br>
<h2>Omni-LPR</h2>
[](https://github.com/habedi/omni-lpr/actions/workflows/tests.yml)
[](https://codecov.io/gh/habedi/omni-lpr)
[](https://www.codefactor.io/repository/github/habedi/omni-lpr)
[](https://github.com/habedi/omni-lpr)
[](https://pypi.org/project/omni-lpr/)
[](https://github.com/habedi/omni-lpr/tree/main/examples)
[](https://github.com/habedi/omni-lpr/blob/main/LICENSE)
<br>
[&logo=docker&logoColor=white&style=flat&color=007ec6)](https://github.com/habedi/omni-lpr/pkgs/container/omni-lpr-cpu)
[&logo=docker&logoColor=white&style=flat&color=007ec6)](https://github.com/habedi/omni-lpr/pkgs/container/omni-lpr-openvino)
[&logo=docker&logoColor=white&style=flat&color=007ec6)](https://github.com/habedi/omni-lpr/pkgs/container/omni-lpr-cuda)
A multi-interface (REST and MCP) server for automatic license plate recognition
</div>
---
Omni-LPR is a self-hostable server that provides automatic license plate recognition (ALPR) capabilities via a REST API
and the Model Context Protocol (MCP). It can be used both as a standalone ALPR microservice and as an ALPR toolbox for
AI agents and large language models (LLMs).
### Why Omni-LPR?
Using Omni-LPR can have the following benefits:
- **Decoupling.** Your main application can be in any programming language. It doesn't need to be tangled up with Python
or specific ML dependencies because the server handles all of that.
- **Multiple Interfaces.** You aren't locked into one way of communicating. You can use a standard REST API from any
app, or you can use MCP, which is designed for AI agent integration.
- **Ready-to-Deploy.** You don't have to build it from scratch. There are pre-built Docker images that are easy to
deploy and start using immediately.
- **Hardware Acceleration.** The server is optimized for the hardware you have. It supports generic CPUs (ONNX), Intel
CPUs (OpenVINO), and NVIDIA GPUs (CUDA).
- **Asynchronous I/O.** It's built on Starlette, which means it has high-performance, non-blocking I/O. It can handle
many concurrent requests without getting bogged down.
- **Scalability.** Because it's a separate service, it can be scaled independently of your main application. If you
suddenly need more ALPR power, you can scale Omni-LPR up without touching anything else.
> [!IMPORTANT]
> Omni-LPR is in early development, so bugs and breaking API changes are expected.
> Please use the [issues page](https://github.com/habedi/omni-lpr/issues) to report bugs or request features.
### Quickstart
You can get started with Omni-LPR in a few minutes by following the steps described below.
#### 1. Install the Server
You can install Omni-LPR using `pip`:
```sh
pip install omni-lpr
```
#### 2. Start the Server
When installed, start the server with a single command:
```sh
omni-lpr
```
By default, the server will be listening on `http://127.0.0.1:8000`.
You can confirm it's running by accessing the health check endpoint:
```sh
curl http://127.0.0.1:8000/api/health
# Expected output: {"status": "ok", "version": "0.2.0"}
```
#### 3. Recognize a License Plate
Now you can make a request to recognize a license plate from an image.
The example below uses a publicly available image URL.
```sh
curl -X POST \
-H "Content-Type: application/json" \
-d '{"path": "https://www.olavsplates.com/foto_n/n_cx11111.jpg"}' \
http://127.0.0.1:8000/api/v1/tools/detect_and_recognize_plate_from_path/invoke
```
You should receive a JSON response with the detected license plate information.
### Usage
Omni-LPR exposes its capabilities as "tools" that can be called via a REST API or over the MCP.
#### Core Tools
- **`list_models`**: Lists the available license plate detector and OCR models.
- **`recognize_plate`**: Recognizes text from a pre-cropped image of a license plate.
- **`detect_and_recognize_plate`**: Detects and recognizes all license plates in a full image.
The server can accept an image in three ways: a Base64-encoded string, a local file path or a URL, or as a direct file
upload. For more details on how to use the different tool variations, please see
the [API Documentation](docs/README.md).
#### REST API
The REST API provides a standard way to interact with the server. All tool endpoints are available under the `/api/v1`
prefix. Once the server is running, you can access interactive API documentation in the Swagger UI
at [http://127.0.0.1:8000/apidoc/swagger](http://127.0.0.1:8000/apidoc/swagger).
#### MCP Interface
The server also exposes its tools over the MCP for integration with AI agents and LLMs. The MCP endpoint is available at
`http://127.0.0.1:8000/mcp/sse`.
You can use a tool like [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to explore the available MCP
tools.
<div align="center">
<picture>
<img src="docs/assets/screenshots/mcp-inspector-2.png" alt="MCP Inspector Screenshot" width="auto">
</picture>
</div>
### Integration
You can connect any client that supports the MCP protocol to the server.
The following examples show how to use the server with [LMStudio](https://lmstudio.ai/).
#### LMStudio Configuration
```json
{
"mcpServers": {
"omni-lpr-local": {
"url": "http://localhost:8000/mcp/sse"
}
}
}
```
#### Tool Usage Examples
The screenshot of using the `list_models` tool in LMStudio to list the available models for the APLR.
<div align="center">
<picture>
<img src="docs/assets/screenshots/lmstudio-list-models-1.png" alt="LMStudio Screenshot 1" width="auto" height="auto">
</picture>
</div>
The screenshot below shows using the `detect_and_recognize_plate_from_path` tool in LMStudio to detect and recognize
the license plate from an [image available on the web](https://www.olavsplates.com/foto_n/n_cx11111.jpg).
<div align="center">
<picture>
<img src="docs/assets/screenshots/lmstudio-detect-plates-1.png" alt="LMStudio Screenshot 2" width="auto" height="auto">
</picture>
</div>
---
### Documentation
Omni-LPR's documentation is available [here](docs).
### Examples
Check out the [examples](examples) directory for usage examples.
### Feature Roadmap
- **Core ALPR Capabilities**
- [x] License plate detection.
- [x] License plate recognition.
- [x] Optimized models for CPU, OpenVINO, and CUDA backends.
- **Interfaces and Developer Experience**
- [x] MCP interface for AI agent integration.
- [x] REST API for all core functions/tools.
- [x] Standardized JSON error responses.
- [x] Interactive API documentation (Swagger UI and ReDoc).
- [x] Support for direct image uploads (`multipart/form-data`).
- **Performance**
- [x] Asynchronous I/O for concurrent requests.
- [x] Prometheus metrics endpoint (`/api/metrics`).
- [ ] Request batching for model inference.
- **Integrations**
- [x] Standalone microservice architecture.
- [x] MCP and REST API usage examples.
- [ ] A Python client library to simplify interaction with the REST API.
- **Deployment**
- [x] Pre-built Docker images for each hardware backend.
- [x] Configuration via environment variables and CLI arguments.
- [ ] A Helm chart for Kubernetes deployment.
- **Benchmarks**
- [ ] Performance benchmarks for different hardware and request types.
---
### Contributing
Contributions are always welcome!
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
### License
Omni-LPR is licensed under the MIT License (see [LICENSE](LICENSE)).
### Acknowledgements
- This project uses the awesome [fast-plate-ocr](https://github.com/ankandrew/fast-plate-ocr)
and [fast-alpr](https://github.com/ankandrew/fast-alpr) Python libraries.
- The project logo is from [SVG Repo](https://www.svgrepo.com/svg/237124/license-plate-number).
Raw data
{
"_id": null,
"home_page": "https://github.com/habedi/omni-lpr",
"name": "omni-lpr",
"maintainer": "Hassan Abedi",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "hassan.abedi.t+omnilpr@gmail.com",
"keywords": "alpr, license plate recognition, automatic license plate recognition, computer vision, rest-api, mcp, microservice, onnx, cuda",
"author": "Hassan Abedi",
"author_email": "hassan.abedi.t+omnilpr@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/71/19/e183c857b8573e5d2e85d0fe606133cc08eac706985b86a39de71bee37fe/omni_lpr-0.2.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <picture>\n <img alt=\"Omni-LPR Logo\" src=\"logo.svg\" width=\"300\">\n </picture>\n<br>\n\n<h2>Omni-LPR</h2>\n\n[](https://github.com/habedi/omni-lpr/actions/workflows/tests.yml)\n[](https://codecov.io/gh/habedi/omni-lpr)\n[](https://www.codefactor.io/repository/github/habedi/omni-lpr)\n[](https://github.com/habedi/omni-lpr)\n[](https://pypi.org/project/omni-lpr/)\n[](https://github.com/habedi/omni-lpr/tree/main/examples)\n[](https://github.com/habedi/omni-lpr/blob/main/LICENSE)\n<br>\n[&logo=docker&logoColor=white&style=flat&color=007ec6)](https://github.com/habedi/omni-lpr/pkgs/container/omni-lpr-cpu)\n[&logo=docker&logoColor=white&style=flat&color=007ec6)](https://github.com/habedi/omni-lpr/pkgs/container/omni-lpr-openvino)\n[&logo=docker&logoColor=white&style=flat&color=007ec6)](https://github.com/habedi/omni-lpr/pkgs/container/omni-lpr-cuda)\n\nA multi-interface (REST and MCP) server for automatic license plate recognition\n\n</div>\n\n---\n\nOmni-LPR is a self-hostable server that provides automatic license plate recognition (ALPR) capabilities via a REST API\nand the Model Context Protocol (MCP). It can be used both as a standalone ALPR microservice and as an ALPR toolbox for\nAI agents and large language models (LLMs).\n\n### Why Omni-LPR?\n\nUsing Omni-LPR can have the following benefits:\n\n- **Decoupling.** Your main application can be in any programming language. It doesn't need to be tangled up with Python\n or specific ML dependencies because the server handles all of that.\n\n- **Multiple Interfaces.** You aren't locked into one way of communicating. You can use a standard REST API from any\n app, or you can use MCP, which is designed for AI agent integration.\n\n- **Ready-to-Deploy.** You don't have to build it from scratch. There are pre-built Docker images that are easy to\n deploy and start using immediately.\n\n- **Hardware Acceleration.** The server is optimized for the hardware you have. It supports generic CPUs (ONNX), Intel\n CPUs (OpenVINO), and NVIDIA GPUs (CUDA).\n\n- **Asynchronous I/O.** It's built on Starlette, which means it has high-performance, non-blocking I/O. It can handle\n many concurrent requests without getting bogged down.\n\n- **Scalability.** Because it's a separate service, it can be scaled independently of your main application. If you\n suddenly need more ALPR power, you can scale Omni-LPR up without touching anything else.\n\n> [!IMPORTANT]\n> Omni-LPR is in early development, so bugs and breaking API changes are expected.\n> Please use the [issues page](https://github.com/habedi/omni-lpr/issues) to report bugs or request features.\n\n### Quickstart\n\nYou can get started with Omni-LPR in a few minutes by following the steps described below.\n\n#### 1. Install the Server\n\nYou can install Omni-LPR using `pip`:\n\n```sh\npip install omni-lpr\n```\n\n#### 2. Start the Server\n\nWhen installed, start the server with a single command:\n\n```sh\nomni-lpr\n```\n\nBy default, the server will be listening on `http://127.0.0.1:8000`.\nYou can confirm it's running by accessing the health check endpoint:\n\n```sh\ncurl http://127.0.0.1:8000/api/health\n# Expected output: {\"status\": \"ok\", \"version\": \"0.2.0\"}\n```\n\n#### 3. Recognize a License Plate\n\nNow you can make a request to recognize a license plate from an image.\nThe example below uses a publicly available image URL.\n\n```sh\ncurl -X POST \\\n -H \"Content-Type: application/json\" \\\n -d '{\"path\": \"https://www.olavsplates.com/foto_n/n_cx11111.jpg\"}' \\\n http://127.0.0.1:8000/api/v1/tools/detect_and_recognize_plate_from_path/invoke\n```\n\nYou should receive a JSON response with the detected license plate information.\n\n### Usage\n\nOmni-LPR exposes its capabilities as \"tools\" that can be called via a REST API or over the MCP.\n\n#### Core Tools\n\n- **`list_models`**: Lists the available license plate detector and OCR models.\n- **`recognize_plate`**: Recognizes text from a pre-cropped image of a license plate.\n- **`detect_and_recognize_plate`**: Detects and recognizes all license plates in a full image.\n\nThe server can accept an image in three ways: a Base64-encoded string, a local file path or a URL, or as a direct file\nupload. For more details on how to use the different tool variations, please see\nthe [API Documentation](docs/README.md).\n\n#### REST API\n\nThe REST API provides a standard way to interact with the server. All tool endpoints are available under the `/api/v1`\nprefix. Once the server is running, you can access interactive API documentation in the Swagger UI\nat [http://127.0.0.1:8000/apidoc/swagger](http://127.0.0.1:8000/apidoc/swagger).\n\n#### MCP Interface\n\nThe server also exposes its tools over the MCP for integration with AI agents and LLMs. The MCP endpoint is available at\n`http://127.0.0.1:8000/mcp/sse`.\n\nYou can use a tool like [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to explore the available MCP\ntools.\n\n<div align=\"center\">\n <picture>\n <img src=\"docs/assets/screenshots/mcp-inspector-2.png\" alt=\"MCP Inspector Screenshot\" width=\"auto\">\n </picture>\n</div>\n\n### Integration\n\nYou can connect any client that supports the MCP protocol to the server.\nThe following examples show how to use the server with [LMStudio](https://lmstudio.ai/).\n\n#### LMStudio Configuration\n\n```json\n{\n \"mcpServers\": {\n \"omni-lpr-local\": {\n \"url\": \"http://localhost:8000/mcp/sse\"\n }\n }\n}\n```\n\n#### Tool Usage Examples\n\nThe screenshot of using the `list_models` tool in LMStudio to list the available models for the APLR.\n\n<div align=\"center\">\n <picture>\n<img src=\"docs/assets/screenshots/lmstudio-list-models-1.png\" alt=\"LMStudio Screenshot 1\" width=\"auto\" height=\"auto\">\n</picture>\n</div>\n\nThe screenshot below shows using the `detect_and_recognize_plate_from_path` tool in LMStudio to detect and recognize\nthe license plate from an [image available on the web](https://www.olavsplates.com/foto_n/n_cx11111.jpg).\n\n<div align=\"center\">\n <picture>\n<img src=\"docs/assets/screenshots/lmstudio-detect-plates-1.png\" alt=\"LMStudio Screenshot 2\" width=\"auto\" height=\"auto\">\n </picture>\n</div>\n\n---\n\n### Documentation\n\nOmni-LPR's documentation is available [here](docs).\n\n### Examples\n\nCheck out the [examples](examples) directory for usage examples.\n\n### Feature Roadmap\n\n- **Core ALPR Capabilities**\n\n - [x] License plate detection.\n - [x] License plate recognition.\n - [x] Optimized models for CPU, OpenVINO, and CUDA backends.\n\n- **Interfaces and Developer Experience**\n\n - [x] MCP interface for AI agent integration.\n - [x] REST API for all core functions/tools.\n - [x] Standardized JSON error responses.\n - [x] Interactive API documentation (Swagger UI and ReDoc).\n - [x] Support for direct image uploads (`multipart/form-data`).\n\n- **Performance**\n\n - [x] Asynchronous I/O for concurrent requests.\n - [x] Prometheus metrics endpoint (`/api/metrics`).\n - [ ] Request batching for model inference.\n\n- **Integrations**\n\n - [x] Standalone microservice architecture.\n - [x] MCP and REST API usage examples.\n - [ ] A Python client library to simplify interaction with the REST API.\n\n- **Deployment**\n\n - [x] Pre-built Docker images for each hardware backend.\n - [x] Configuration via environment variables and CLI arguments.\n - [ ] A Helm chart for Kubernetes deployment.\n\n- **Benchmarks**\n\n - [ ] Performance benchmarks for different hardware and request types.\n\n---\n\n### Contributing\n\nContributions are always welcome!\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.\n\n### License\n\nOmni-LPR is licensed under the MIT License (see [LICENSE](LICENSE)).\n\n### Acknowledgements\n\n- This project uses the awesome [fast-plate-ocr](https://github.com/ankandrew/fast-plate-ocr)\n and [fast-alpr](https://github.com/ankandrew/fast-alpr) Python libraries.\n- The project logo is from [SVG Repo](https://www.svgrepo.com/svg/237124/license-plate-number).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": " A multi-interface (REST and MCP) server for automatic license plate recognition",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/habedi/omni-lpr/blob/main/README.md",
"Homepage": "https://github.com/habedi/omni-lpr",
"Repository": "https://github.com/habedi/omni-lpr"
},
"split_keywords": [
"alpr",
" license plate recognition",
" automatic license plate recognition",
" computer vision",
" rest-api",
" mcp",
" microservice",
" onnx",
" cuda"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "81661174d8befad67425b33b2589520ed3f4df0b81b69ef434298da17163ae54",
"md5": "fa964d806667baa9ae4474333241b81d",
"sha256": "69362c849f1ab9044f67e79af6fd1e2a55f19211df64124578154ac599f0cb23"
},
"downloads": -1,
"filename": "omni_lpr-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa964d806667baa9ae4474333241b81d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 18580,
"upload_time": "2025-08-31T16:13:29",
"upload_time_iso_8601": "2025-08-31T16:13:29.670304Z",
"url": "https://files.pythonhosted.org/packages/81/66/1174d8befad67425b33b2589520ed3f4df0b81b69ef434298da17163ae54/omni_lpr-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7119e183c857b8573e5d2e85d0fe606133cc08eac706985b86a39de71bee37fe",
"md5": "d868f3ba65278c9683a7560f129a0335",
"sha256": "3ef66b3ef15145196df3dcd4e050ce52da225a47a38fe47bdcfb72e0cace0203"
},
"downloads": -1,
"filename": "omni_lpr-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "d868f3ba65278c9683a7560f129a0335",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 19180,
"upload_time": "2025-08-31T16:13:30",
"upload_time_iso_8601": "2025-08-31T16:13:30.811378Z",
"url": "https://files.pythonhosted.org/packages/71/19/e183c857b8573e5d2e85d0fe606133cc08eac706985b86a39de71bee37fe/omni_lpr-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 16:13:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "habedi",
"github_project": "omni-lpr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "omni-lpr"
}
JSON
