fastocr-mcp 0.1.0__tar.gz

fastocr_mcp-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+.mcpregistry_*

fastocr_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this server are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[semantic versioning](https://semver.org).
+
+## [0.1.0] - 2026-10-24
+
+First release. A stdio MCP server for the FastOCR Document OCR API with the tools
+`ocr_file` (a local PDF, PNG, JPG, JPEG, GIF, WebP or BMP file), `get_document`,
+`list_documents` and `delete_document`. `ocr_pdf` is the same tool as `ocr_file` under its
+earlier name. Needs `fastocr-sdk` 0.2.0 or later for image uploads. API requests send the
+User-Agent `fastocr-mcp/<version>` followed by the SDK's own.

fastocr_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FastOCR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastocr_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.5
+Name: fastocr-mcp
+Version: 0.1.0
+Summary: MCP server for the FastOCR Document OCR API: OCR scanned PDFs into text or searchable PDFs from Claude, Cursor and other MCP clients.
+Project-URL: Homepage, https://fastocr.org
+Project-URL: Documentation, https://fastocr.org/docs
+Project-URL: Repository, https://github.com/fastocr-org/fastocr-mcp
+Project-URL: Changelog, https://github.com/fastocr-org/fastocr-mcp/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/fastocr-org/fastocr-mcp/issues
+Author-email: FastOCR <support@fastocr.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,fastocr,mcp,model-context-protocol,ocr,pdf,searchable-pdf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastocr-sdk<0.3,>=0.2.0
+Requires-Dist: mcp<3,>=2.3.0
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.20.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<a href="https://fastocr.org"><img src="https://raw.githubusercontent.com/fastocr-org/fastocr-mcp/main/docs/images/logo.png" alt="FastOCR" width="56" height="56"></a>
+
+# FastOCR MCP server
+
+OCR any scanned PDF or image from Claude, Cursor and other MCP clients, in 100+ languages. **[fastocr.org](https://fastocr.org)** · [Docs](https://fastocr.org/docs) · [Get an API key](https://fastocr.org/developers/keys)
+
+<!-- mcp-name: io.github.fastocr-org/fastocr-mcp -->
+
+[![PyPI](https://img.shields.io/pypi/v/fastocr-mcp.svg)](https://pypi.org/project/fastocr-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) server for the
+[FastOCR Document OCR API](https://fastocr.org/docs). It lets Claude Desktop,
+Claude Code, Cursor and other MCP clients OCR a local scanned PDF or image and get
+back its text or a searchable PDF.
+
+- PDF files up to 1 GiB, and PNG, JPG, JPEG, GIF, WebP and BMP images up to 20 MiB; 100+ languages.
+- Built on the official [`fastocr-sdk`](https://pypi.org/project/fastocr-sdk/) and the
+  official MCP Python SDK. Runs locally over stdio; your files go only to the FastOCR API.
+
+![A scanned Arabic book page beside the text FastOCR returned for it](https://raw.githubusercontent.com/fastocr-org/fastocr-mcp/main/docs/images/ocr-before-after.png)
+
+A real scanned page and the first lines of the text FastOCR returned for it, unedited.
+
+API reference and guides: **https://fastocr.org/docs**
+
+## Get an API key
+
+Any signed-in FastOCR account can create an API key and start right away.
+
+1. Sign in and create an API key in the
+   [developer console](https://fastocr.org/developers/keys). You accept the
+   [API terms](https://fastocr.org/api-terms) with your first key.
+2. Set the key as `FASTOCR_API_KEY` in your MCP client config (see below).
+3. When you need more than the free pages, buy a prepaid API page pack by card in the
+   [developer console](https://fastocr.org/developers/keys#buy-api-pages).
+
+Each account gets 50 free document pages per month.
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/) there is nothing to install; MCP clients run it with
+`uvx fastocr-mcp`. Or install it with pip and run `fastocr-mcp`:
+
+```bash
+pip install fastocr-mcp
+```
+
+Python 3.10 or newer. The server reads the key from `FASTOCR_API_KEY`.
+
+## Configure your MCP client
+
+### Claude Code
+
+```bash
+claude mcp add fastocr -e FASTOCR_API_KEY=your_api_key -- uvx fastocr-mcp
+```
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json` (Settings > Developer > Edit Config), then restart
+Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "fastocr": {
+      "command": "uvx",
+      "args": ["fastocr-mcp"],
+      "env": { "FASTOCR_API_KEY": "your_api_key" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "fastocr": {
+      "command": "uvx",
+      "args": ["fastocr-mcp"],
+      "env": { "FASTOCR_API_KEY": "your_api_key" }
+    }
+  }
+}
+```
+
+If you installed with pip, use `"command": "fastocr-mcp"` and `"args": []`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `ocr_file(path, output="text", output_path=None)` | Uploads a local PDF or image, runs OCR and waits up to 45 seconds; a larger document returns its id for `get_document`. `output="text"` returns the text (text over 20,000 characters is cut, and the full text is saved to `output_path` or `<file>.ocr.txt` next to the input file). `output="pdf"` saves a searchable PDF to `output_path` or `<file>.searchable.pdf`. |
+| `ocr_pdf(path, output="text", output_path=None)` | The same tool as `ocr_file` under its earlier name, kept so existing setups keep working. |
+| `get_document(document_id, output="status", output_path=None)` | Status and page counts of a document; with `output="text"` or `"pdf"`, waits up to 45 seconds and fetches the finished result. Fetching a result again costs no pages. |
+| `list_documents(limit=20)` | The most recent documents in the account, newest first. |
+| `delete_document(document_id)` | Deletes a document and its stored files on FastOCR. Local files are not touched. |
+
+Try asking: *"OCR ~/Downloads/scanned-contract.pdf and summarize the termination clause"*,
+*"Read the text in /Users/me/Desktop/receipt.jpg"* or
+*"Make a searchable copy of /Users/me/archive/1998-letters.pdf"*.
+
+Every processed page uses one page of the account's API allowance; an image is one page. A document that runs out
+of pages fails with `buy_pages`; the tool says so and links to the
+[developer console](https://fastocr.org/developers/keys#buy-api-pages).
+
+## Errors
+
+Tool errors are written for the agent to act on: a rejected key, an account out of pages
+(`buy_pages`), too many documents processing at once (`concurrency_limit`), a missing file, or an
+unsupported file type. Each message says what to do next. Error codes are listed in the
+[API docs](https://fastocr.org/docs/documents).
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `FASTOCR_API_KEY` | Required. Your API key. |
+| `FASTOCR_BASE_URL` | Optional. Overrides `https://api.fastocr.org`. |
+
+## Links
+
+- Docs: https://fastocr.org/docs
+- API keys and page packs: https://fastocr.org/developers/keys
+- Python SDK: https://github.com/fastocr-org/fastocr-python
+- Support: support@fastocr.org
+
+## License
+
+MIT

fastocr_mcp-0.1.0/README.md

@@ -0,0 +1,135 @@
+<a href="https://fastocr.org"><img src="https://raw.githubusercontent.com/fastocr-org/fastocr-mcp/main/docs/images/logo.png" alt="FastOCR" width="56" height="56"></a>
+
+# FastOCR MCP server
+
+OCR any scanned PDF or image from Claude, Cursor and other MCP clients, in 100+ languages. **[fastocr.org](https://fastocr.org)** · [Docs](https://fastocr.org/docs) · [Get an API key](https://fastocr.org/developers/keys)
+
+<!-- mcp-name: io.github.fastocr-org/fastocr-mcp -->
+
+[![PyPI](https://img.shields.io/pypi/v/fastocr-mcp.svg)](https://pypi.org/project/fastocr-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) server for the
+[FastOCR Document OCR API](https://fastocr.org/docs). It lets Claude Desktop,
+Claude Code, Cursor and other MCP clients OCR a local scanned PDF or image and get
+back its text or a searchable PDF.
+
+- PDF files up to 1 GiB, and PNG, JPG, JPEG, GIF, WebP and BMP images up to 20 MiB; 100+ languages.
+- Built on the official [`fastocr-sdk`](https://pypi.org/project/fastocr-sdk/) and the
+  official MCP Python SDK. Runs locally over stdio; your files go only to the FastOCR API.
+
+![A scanned Arabic book page beside the text FastOCR returned for it](https://raw.githubusercontent.com/fastocr-org/fastocr-mcp/main/docs/images/ocr-before-after.png)
+
+A real scanned page and the first lines of the text FastOCR returned for it, unedited.
+
+API reference and guides: **https://fastocr.org/docs**
+
+## Get an API key
+
+Any signed-in FastOCR account can create an API key and start right away.
+
+1. Sign in and create an API key in the
+   [developer console](https://fastocr.org/developers/keys). You accept the
+   [API terms](https://fastocr.org/api-terms) with your first key.
+2. Set the key as `FASTOCR_API_KEY` in your MCP client config (see below).
+3. When you need more than the free pages, buy a prepaid API page pack by card in the
+   [developer console](https://fastocr.org/developers/keys#buy-api-pages).
+
+Each account gets 50 free document pages per month.
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/) there is nothing to install; MCP clients run it with
+`uvx fastocr-mcp`. Or install it with pip and run `fastocr-mcp`:
+
+```bash
+pip install fastocr-mcp
+```
+
+Python 3.10 or newer. The server reads the key from `FASTOCR_API_KEY`.
+
+## Configure your MCP client
+
+### Claude Code
+
+```bash
+claude mcp add fastocr -e FASTOCR_API_KEY=your_api_key -- uvx fastocr-mcp
+```
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json` (Settings > Developer > Edit Config), then restart
+Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "fastocr": {
+      "command": "uvx",
+      "args": ["fastocr-mcp"],
+      "env": { "FASTOCR_API_KEY": "your_api_key" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "fastocr": {
+      "command": "uvx",
+      "args": ["fastocr-mcp"],
+      "env": { "FASTOCR_API_KEY": "your_api_key" }
+    }
+  }
+}
+```
+
+If you installed with pip, use `"command": "fastocr-mcp"` and `"args": []`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `ocr_file(path, output="text", output_path=None)` | Uploads a local PDF or image, runs OCR and waits up to 45 seconds; a larger document returns its id for `get_document`. `output="text"` returns the text (text over 20,000 characters is cut, and the full text is saved to `output_path` or `<file>.ocr.txt` next to the input file). `output="pdf"` saves a searchable PDF to `output_path` or `<file>.searchable.pdf`. |
+| `ocr_pdf(path, output="text", output_path=None)` | The same tool as `ocr_file` under its earlier name, kept so existing setups keep working. |
+| `get_document(document_id, output="status", output_path=None)` | Status and page counts of a document; with `output="text"` or `"pdf"`, waits up to 45 seconds and fetches the finished result. Fetching a result again costs no pages. |
+| `list_documents(limit=20)` | The most recent documents in the account, newest first. |
+| `delete_document(document_id)` | Deletes a document and its stored files on FastOCR. Local files are not touched. |
+
+Try asking: *"OCR ~/Downloads/scanned-contract.pdf and summarize the termination clause"*,
+*"Read the text in /Users/me/Desktop/receipt.jpg"* or
+*"Make a searchable copy of /Users/me/archive/1998-letters.pdf"*.
+
+Every processed page uses one page of the account's API allowance; an image is one page. A document that runs out
+of pages fails with `buy_pages`; the tool says so and links to the
+[developer console](https://fastocr.org/developers/keys#buy-api-pages).
+
+## Errors
+
+Tool errors are written for the agent to act on: a rejected key, an account out of pages
+(`buy_pages`), too many documents processing at once (`concurrency_limit`), a missing file, or an
+unsupported file type. Each message says what to do next. Error codes are listed in the
+[API docs](https://fastocr.org/docs/documents).
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `FASTOCR_API_KEY` | Required. Your API key. |
+| `FASTOCR_BASE_URL` | Optional. Overrides `https://api.fastocr.org`. |
+
+## Links
+
+- Docs: https://fastocr.org/docs
+- API keys and page packs: https://fastocr.org/developers/keys
+- Python SDK: https://github.com/fastocr-org/fastocr-python
+- Support: support@fastocr.org
+
+## License
+
+MIT

fastocr_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastocr-mcp"
+dynamic = ["version"]
+description = "MCP server for the FastOCR Document OCR API: OCR scanned PDFs into text or searchable PDFs from Claude, Cursor and other MCP clients."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["mcp", "model-context-protocol", "ocr", "pdf", "searchable-pdf", "ai-agents", "fastocr"]
+authors = [
+    { name = "FastOCR", email = "support@fastocr.org" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastocr-sdk>=0.2.0,<0.3",
+    "mcp>=2.3.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.23.0",
+    "respx>=0.21.0",
+    "jsonschema>=4.20.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+fastocr-mcp = "fastocr_mcp.server:main"
+
+[project.urls]
+Homepage = "https://fastocr.org"
+Documentation = "https://fastocr.org/docs"
+Repository = "https://github.com/fastocr-org/fastocr-mcp"
+Changelog = "https://github.com/fastocr-org/fastocr-mcp/blob/main/CHANGELOG.md"
+Issues = "https://github.com/fastocr-org/fastocr-mcp/issues"
+
+[tool.hatch.version]
+path = "src/fastocr_mcp/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastocr_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md", "server.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]

fastocr_mcp-0.1.0/server.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.fastocr-org/fastocr-mcp",
+  "title": "FastOCR",
+  "description": "OCR scanned PDFs and images into text or searchable PDFs with the FastOCR API.",
+  "websiteUrl": "https://fastocr.org/docs",
+  "repository": {
+    "url": "https://github.com/fastocr-org/fastocr-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "fastocr-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "FASTOCR_API_KEY",
+          "description": "FastOCR API key from https://fastocr.org/developers/keys",
+          "isRequired": true,
+          "isSecret": true
+        }
+      ]
+    }
+  ]
+}

fastocr_mcp-0.1.0/src/fastocr_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""FastOCR MCP server: OCR local PDFs from any MCP client."""
+
+from ._version import __version__
+from .server import create_server, main
+
+__all__ = ["__version__", "create_server", "main"]

fastocr_mcp-0.1.0/src/fastocr_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()

fastocr_mcp-0.1.0/src/fastocr_mcp/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"