io.github.hydrojwh/promptready-mcp
Convert PDF/CSV to Markdown with AI-powered OCR via the PromptReady cloud API.
Open source Open in the app JSON README (API)
About
Convert PDF/CSV to Markdown with AI-powered OCR via the PromptReady cloud API.
Details
- Kind
- MCP servers
- Topic
- Files & documents
- Publisher
- hydrojwh
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.7
- Last push
- 2026-09-04T12:51:26Z
- Repository state
- ativo
- Language
- Python
- License
- NOASSERTION
- Added
- 2026-09-04 03:00:52
- Updated
- 2026-09-04 14:00:37
- Origin id
io.github.hydrojwh/promptready-mcp
README
# PromptReady MCP
<!-- mcp-name: io.github.hydrojwh/promptready-mcp -->
Official [Model Context Protocol](https://modelcontextprotocol.io/) client for
[PromptReady](https://promptready.space) — convert PDF/CSV to Markdown from AI
agents (Grok, Claude Code, Cursor, and other MCP hosts).
**Same PromptReady account and credits as the web app.**
## Features
- Browser Google login (tokens stay on your machine)
- `get_credits`, `convert_pdf`, `get_status`, `wait_and_download`
- Slash commands for humans: `/promptready:convert` and five more (below)
- Saved convert defaults (engine, tables, images) — not on every call
- Factory default: **PaddleOCR-VL**, tables on, images off
## Install
```bash
pip install promptready-mcp
```
Or run it without installing:
```bash
uvx promptready-mcp
```
<details>
<summary>From source</summary>
```bash
git clone https://github.com/hydrojwh/promptready-mcp.git
cd promptready-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
```
</details>
## Login (once per machine)
```bash
promptready-mcp-login
```
If you installed with `uvx`, the login command lives in the same package:
```bash
uvx --from promptready-mcp promptready-mcp-login
```
Either opens Google OAuth and saves credentials to
`~/.config/promptready/credentials.json` (file mode `0600`). That path is in your
home directory, so it survives `uvx` cache resets. You can also log in from inside
an MCP host by calling the `login` tool.
After you sign in, the browser returns to `http://127.0.0.1:18765/callback` — a
local page started by the login command. No Supabase configuration is needed.
<details>
<summary>Email login fallback</summary>
If browser-based Google login is not an option, the same command accepts email
and password:
```bash
promptready-mcp-login --email you@x.com
```
Leave out `--password` and you will be prompted for it instead — this keeps the
password out of your shell history.
</details>
Already have an access token? Set `PROMPTREADY_ACCESS_TOKEN` in the environment
(MCP host or shell). Environment variables take precedence over the saved
credentials file.
## MCP host config
### Fastest: let your AI agent install it
If you are already in an MCP-capable agent, skip the JSON editing and just
ask:
> Install the PromptReady MCP server for me. The PyPI package is
> `promptready-mcp` (stdio command `promptready-mcp`). Add it to your MCP
> config, then I will run the `login` tool.
In Claude Code the agent can use the built-in CLI:
```bash
claude mcp add promptready -- promptready-mcp
```
### Reconnect after changing config
Hosts do not pick up MCP config changes mid-session. After changing the
config, restart the host or reconnect the server — in Claude Code, open the
`/mcp` panel and reconnect.
The `/mcp` panel shows server status and lists the connected servers'
tools, but it does **not** run them: picking a tool in that list will
not invoke it. Tools are invoked through normal conversation — ask the
agent to convert a file and it calls `convert_pdf` for you. If a call
fails, reconnect from the panel first.
### Claude Code
```bash
claude mcp add promptready -- promptready-mcp
```
The default scope is `local` (this project only). Use `--scope user` to
register it for all your projects, or `--scope project` to share the
registration through a committed `.mcp.json`.
### Cursor
Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` for a single project):
```json
{
"mcpServers": {
"promptready": {
"command": "promptready-mcp"
}
}
}
```
### Grok
```toml
[mcp_servers.promptready]
command = "promptready-mcp"
enabled = true
tool_timeout_sec = 3600
```
### Claude Desktop / generic JSON
```json
{
"mcpServers": {
"promptready": {
"command": "promptready-mcp"
}
}
}
```
No access token in config files required after login.
<details>
<summary>Host cannot find <code>promptready-mcp</code></summary>
GUI hosts start servers with a narrow `PATH`, so a console script installed by
`pip install --user` is often invisible to them — the host reports a spawn
failure or "server disconnected" rather than a missing command.
Two reliable fixes:
```json
{ "mcpServers": { "promptready": {
"command": "uvx", "args": ["promptready-mcp"] } } }
```
or point at the absolute path of the script:
`/ABS/PATH/.venv/bin/promptready-mcp`.
</details>
## Tools
| Tool | Purpose |
|------|---------|
| `login` / `logout` | Browser auth / clear local credentials |
| `get_credits` | Credit balance |
| `get_convert_settings` / `set_convert_settings` | Saved convert defaults |
| `convert_pdf` | Upload path → queue (optional `wait`) |
| `get_status` | Job status |
| `wait_and_download` | Poll + save `.md` |
Downloaded names follow the web app: `{name}_PaddleOCR-VL.md` (engine label).
Credits are deducted by the server when a job is queued, exactly as on the web
app. `convert_pdf(wait=True)` can run for a long time, so give the host a high
tool timeout.
## Slash commands
MCP *prompts* are the human entry point: instead of describing what you
want, you pick a command. Hosts that surface prompts as slash commands
(Claude Code does) show them as `/promptready:<name>`:
| Slash command | Purpose |
|---------------|---------|
| `/promptready:login` | Log in (opens the browser Google sign-in) |
| `/promptready:logout` | Log out on this machine |
| `/promptready:credits` | Show your credit balance |
| `/promptready:convert` | Convert a PDF/CSV to Markdown |
| `/promptready:site` | Show the PromptReady web app URL |
| `/promptready:settings` | Show — and optionally change — convert defaults |
Each command expands to a short instruction; the agent then calls the
matching tool (`login`, `get_credits`, `convert_pdf`, …) for you.
`/promptready:convert` optionally takes two positional arguments, input
path then output directory. Pick the command from the slash menu (hosts
may list it as `promptready:convert (MCP)`) and append the arguments:
```text
/promptready:convert (MCP) report.pdf markdown-out
```
Arguments are split on whitespace and cannot be quoted, so paths with
spaces do not fit on the command line — run the command bare and give
the paths in chat instead. With no arguments the command asks you for
them. The conversion itself always goes through the `convert_pdf` tool:
never re-run it for the same file while a download is pending — that
queues a fresh conversion and spends fresh credits; the expanded command
tells the agent to call `wait_and_download` instead.
Hosts that do not map prompts to slash commands simply ignore this
section; the tools keep working as before.
## Security
- Tokens are **never** hardcoded in this repository.
- Do **not** commit `~/.config/promptready/*` or `.env`.
- Only use the official package linked from https://promptready.space
- Vulnerability reports: see [SECURITY.md](SECURITY.md)
## Service terms
Using the cloud API is subject to the
[Terms of Service](https://promptready.space/legal/terms-of-service.en.md) and
[Privacy Policy](https://promptready.space/legal/privacy-policy.en.md).
This MIT-licensed client does not grant free unlimited conversion.
## Smoke test (no account)
```bash
./scripts/smoke_stdio.sh
```
## License
MIT — see [LICENSE](LICENSE).