# PDF Extraction MCP Server

A remote MCP server that gives Claude the ability to extract text and metadata from PDF files. Add it as a custom connector on claude.ai.

---

## Tools exposed to Claude

| Tool | Description |
|---|---|
| `extract_text_from_url` | Download a PDF from a public URL and return its text |
| `extract_text_from_base64` | Extract text from a base64-encoded PDF |
| `get_pdf_metadata` | Return page count, title, author, dates — without full text |

---

## Quick start (local)

```bash
npm install
npm start
# Server runs on http://localhost:3000
```

To test locally with Claude Desktop, use `mcp-remote`:

```json
// claude_desktop_config.json
{
  "mcpServers": {
    "pdf-extraction": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}
```

---

## Deploy to the internet (required for claude.ai connector)

Claude.ai connectors require a **publicly accessible HTTPS URL**.

### Option A — Railway (easiest, free tier available)

1. Push this repo to GitHub.
2. Go to [railway.app](https://railway.app) → New Project → Deploy from GitHub repo.
3. Railway auto-detects the Dockerfile and deploys.
4. Set env vars in Railway dashboard (e.g. `API_KEY`).
5. Railway gives you a public HTTPS URL like `https://pdf-mcp-production.up.railway.app`.

### Option B — Render

1. Push to GitHub.
2. Go to [render.com](https://render.com) → New Web Service → connect repo.
3. Runtime: Docker. Set env vars.
4. Render gives you `https://your-service.onrender.com`.

### Option C — Fly.io

```bash
fly launch          # follow prompts, auto-detects Dockerfile
fly secrets set API_KEY=your-secret
fly deploy
```

### Option D — Docker anywhere (VPS / cloud VM)

```bash
docker compose up -d
# Then expose port 3000 via nginx + Let's Encrypt for HTTPS
```

---

## Add to Claude.ai as a connector

> Requires Pro, Max, Team, or Enterprise plan.

1. Open [claude.ai](https://claude.ai) → click your avatar → **Settings**.
2. Navigate to **Connectors**.
3. Click **"Add custom connector"**.
4. Enter your server's MCP endpoint URL:
   ```
   https://your-deployed-server.example.com/mcp
   ```
5. If you set `API_KEY`, click **Advanced settings** and enter it as the OAuth Client Secret (or pass it via a Bearer header using `mcp-remote` for Desktop).
6. Click **Add**.

Claude will now have access to the three PDF tools in every conversation.

---

## Authentication

The server supports two modes:

**Authless (default MVP mode)** — anyone who knows your URL can use it. Fine for personal use.

**Bearer token** — set the `API_KEY` environment variable. Callers must include:
```
Authorization: Bearer <your-key>
```

For a production connector with user-level OAuth, see the [MCP auth spec](https://support.claude.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers).

---

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3000` | HTTP port |
| `API_KEY` | _(unset)_ | When set, requires `Authorization: Bearer <key>` |

---

## Extending the server

Add a new tool in `src/server.js` by calling `server.tool(name, description, schema, handler)`. The MCP SDK handles all protocol framing automatically.

Ideas for next tools:
- `extract_tables` — extract tabular data from PDFs
- `search_pdf` — search for a keyword across pages
- `split_pages` — return text page-by-page
- `summarize_pdf` — pipe extracted text back through Claude API