Metadata-Version: 2.5
Name: mcp-papra
Version: 0.1.0
Summary: MCP server for Papra: search, read and tag your documents from Claude. Read-only by default.
License-Expression: MIT
License-File: LICENSE
Keywords: documents,mcp,model-context-protocol,papra
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: respx; extra == 'test'
Description-Content-Type: text/markdown

# mcp-papra

An MCP server that lets Claude search, read and tag the documents in your [Papra](https://papra.app) instance — read-only by default.

## Install

```bash
pip install mcp-papra      # or run it without installing: uvx mcp-papra
```

Create an API key in Papra (read permissions are enough), then set:

| Variable | Meaning |
|---|---|
| `PAPRA_API_KEY` | API key (required unless demo mode) |
| `PAPRA_URL` | Papra API URL (default `https://api.papra.app`; use your own for self-hosted) |
| `PAPRA_ORGANIZATION_ID` | Organization id (optional if the key only sees one) |
| `PAPRA_ALLOW_WRITE=1` | Also expose `upload_document` and `tag_document` |
| `PAPRA_DEMO=1` | Fictional documents, no key and no network |

## Use with Claude Code

```bash
claude mcp add papra --env PAPRA_API_KEY=your_key -- uvx mcp-papra
# try it without any account:
claude mcp add papra-demo --env PAPRA_DEMO=1 -- uvx mcp-papra
```

## Use with Claude Desktop

In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "papra": {
      "command": "uvx",
      "args": ["mcp-papra"],
      "env": { "PAPRA_API_KEY": "your_key" }
    }
  }
}
```

## Tools

| Tool | Mode | What it does |
|---|---|---|
| `search_documents(query, limit)` | read | Search with Papra's advanced syntax (`tag:contract AND created:>2024`, `-has:tags`, …); returns metadata, not text |
| `get_document(document_id, max_chars)` | read | Metadata and extracted text, truncated to `max_chars` |
| `summarize_by_tag(tag, limit)` | read | Name and excerpt of each document with a tag (Papra has tags, not folders); Claude writes the summary |
| `upload_document(path, ocr_languages)` | write | Upload a local file |
| `tag_document(document_id, tag_name)` | write | Attach a tag, creating it if needed |

Write tools exist only when `PAPRA_ALLOW_WRITE=1`. This is an unofficial project, not affiliated with Papra.

## Development

```bash
pip install -e ".[test]" && pytest   # no network needed
```

MIT licensed.
