QUICKSTART.mdā¢4.33 kB
# Quick Start Guide
## Installation
1. Clone or download this repository
2. Install dependencies:
```bash
uv pip install -e .
```
## Quick Test
1. Create a test PDF:
```bash
cd examples
uv run python create_test_pdf.py
```
2. Run the integration test:
```bash
cd ..
uv run python examples/test_integration.py
```
3. Check the results:
- Original: `examples/test_document.pdf`
- Redacted: `examples/test_document_redacted.pdf`
## Running the Server
### Option 1: stdio (for local MCP clients)
```bash
python -m redact_mcp.server
```
### Option 2: HTTP (for remote access)
```bash
fastmcp run redact_mcp.server:mcp --transport http --port 8000
```
## Using with Claude Desktop
1. Copy your installation path:
```bash
pwd
```
2. Edit your Claude Desktop config:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
3. Add this configuration (replace `/path/to/redact_mcp` with your actual path):
```json
{
"mcpServers": {
"pdf-redaction": {
"command": "uv",
"args": [
"--directory",
"/path/to/redact_mcp",
"run",
"fastmcp",
"run",
"redact_mcp.server:mcp"
]
}
}
}
```
4. Restart Claude Desktop
## Example Conversation with Claude
Once configured, you can have conversations like:
**You**: "Load the PDF at /Users/me/documents/report.pdf"
**Claude**: *Uses load_pdf tool and shows you the content*
**You**: "Redact all instances of 'confidential', 'John Doe', and the email address 'john@example.com'"
**Claude**: *Uses redact_text tool with all three texts at once*
**You**: "What have you redacted so far?"
**Claude**: *Uses list_applied_redactions tool to show the list*
**You**: "Also redact the social security number 123-45-6789"
**Claude**: *Uses redact_text tool - automatically skips any already-redacted texts*
**You**: "Save the redacted version"
**Claude**: *Uses save_redacted_pdf tool and confirms the file path*
## Common Use Cases
### Redacting Personal Information (Batch Mode - Recommended)
```
1. Load /path/to/document.pdf
2. Redact ["John Doe", "123-45-6789", "john.doe@email.com"] (all at once!)
3. Check what was redacted with list_applied_redactions
4. Save the redacted PDF
```
### Redacting Personal Information (Step-by-Step)
```
1. Load /path/to/document.pdf
2. Redact ["John Doe"]
3. Redact ["123-45-6789"]
4. Redact ["john.doe@email.com"]
5. Save the redacted PDF
```
### Redacting Financial Data
```
1. Load /path/to/financial_report.pdf
2. Redact ["Account: ", "Card Number", "Balance:"] (batch redaction)
3. List applied redactions to verify
4. Save as /path/to/financial_report_public.pdf
```
### Batch Redaction
You can load multiple PDFs and redact them sequentially:
```
1. Load document1.pdf
2. Redact ["sensitive", "confidential", "private"] in document1.pdf
3. Save document1.pdf
4. Load document2.pdf
5. Redact ["sensitive", "confidential", "private"] in document2.pdf
6. Save document2.pdf
```
## Tips
- Always load a PDF before attempting to redact it
- **Use batch redaction**: Redact multiple texts at once for better performance (e.g., `["text1", "text2", "text3"]`)
- Use `list_applied_redactions` to check what has been redacted and avoid duplicate work
- You can redact the same PDF multiple times before saving
- The tool automatically skips texts that have already been redacted
- The default output filename adds "_redacted" to the original name
- Redactions are applied permanently when you save
- Close PDFs when done to free memory (this also clears redaction tracking)
- Use list_loaded_pdfs to see which PDFs are currently loaded
## Troubleshooting
### "PDF not loaded" error
Make sure to load the PDF first using the load_pdf tool.
### File not found
Provide absolute paths or paths relative to where the server is running.
### Memory issues with large PDFs
Close PDFs after you're done with them using close_pdf.
## Advanced: Area-Based Redaction
You can redact specific rectangular areas by coordinates:
```
Redact the area from (100, 100) to (300, 150) on page 1 of document.pdf
```
This is useful when you need to redact specific regions rather than text strings.