# PDF MCP Server

An MCP server that exposes PDF files as resources, page by page, over Streamable HTTP.

## Setup

Create and activate a virtual environment, then install dependencies:

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

## Launch

```bash
fastmcp run server.py --transport http
```

The MCP endpoint will be available at `http://localhost:8000/mcp`.

### Options

| Flag | Default | Description |
| ---- | ------- | ----------- |
| `--host` | `127.0.0.1` | Bind address |
| `--port` | `8000` | Port |
| `--reload` | off | Restart on file changes (dev mode) |

Example with custom port:

```bash
fastmcp run server.py --transport http --port 9000
```

## Resources

Place PDF files in the same directory as `server.py`. Three resource URIs are exposed:

| URI | Returns |
| --- | ------- |
| `pdf://list` | List of all PDF filenames in the server directory |
| `pdf://{filename}/info` | Page count and metadata for the given PDF |
| `pdf://{filename}/page/{page}` | Extracted text of page `{page}` (1-indexed) |

### Example

```text
pdf://list
pdf://my_document.pdf/info
pdf://my_document.pdf/page/1
```

## Running and testing

Use fastmcp (on cli) to run the server (and select the transport form)

```bash
fastmcp run server.py --transport http
```

Inspecting can be done with

```bash
npx @modelcontextprotocol/inspector
```

and connect after giving the URL returned by `fastmcp` command (usually `http://127.0.0.1:8000/mcp`) with a `Streamable http` transport type.

## References

- [FreeCodeCamp's "How to build an mcp server with python" tutorial](https://www.freecodecamp.org/news/how-to-build-an-mcp-server-with-python-docker-and-claude-code/)
- [MCP documentation](https://modelcontextprotocol.io/docs/getting-started/intro)
- [FastMCP portal](https://gofastmcp.com/getting-started/welcome)