PDFluent

pdfluent-mcp

PDFluent 用の MCP サーバーです。Claude Desktop、Claude Code、Cursor、VS Code、その他あらゆる MCP クライアントで、ローカルの PDF を Markdown、プレーンテキスト、表、または位置情報付きブロックとして読み取り、メタデータを確認し、検索し、フォームフィールドに入力して新しいファイルを作成できます。

stdio で動作し、クライアントごとに 1 つのプロセスを起動して、pdfluent Python パッケージ上で実行されます。ドキュメントはお使いのマシン内に保持されます。サーバーは、許可したディレクトリ内のみを読み書きします。balanced 品質ティアではモデルファイルが必要です。pdfluent models install を実行すると、モデルファイルを一度ダウンロードします。ドキュメントがアップロードされることはありません。

ツール

ツール	戻り値
extract_markdown(path, pages?, quality?)	読み順に並べた Markdown 形式のドキュメントです。見出し、リスト項目、表が含まれます。柱とページ番号は除外されます。quality は fast（デフォルト）または balanced です。
extract_text(path, pages?)	ページごとのプレーンテキストレイヤーです。各ページの前には `` が付加されます。
extract_tables(path, pages?)	tables：各表につき 1 つのエントリーが含まれ、page、rows（セル文字列のリスト）、header_rows を持ちます。
extract_blocks(path, pages?, include_furniture?)	blocks：各ブロックに kind、text、page、bbox、confidence が含まれ、該当する場合は level、ordinal、または表のセル位置も含まれます。pages_needing_vision：テキストレイヤーがないページです。
get_metadata(path)	ページ数、タイトル、作成者、日付、PDF バージョン、暗号化の有無、ドキュメントにフォームフィールドがあるかどうか、署名とブックマークの数、テキストレイヤーがないページを返します。
search(path, query)	query が見つかったページと、ページごとの最大 3 件の抜粋を返します。
list_form_fields(path)	各フォームフィールドの name、type、value、page を返します。
fill_form(path, values, out_path, overwrite?)	指定したフィールドに入力し、out_path に新しいファイルを書き込みます。入力ファイルは変更されません。既存の out_path は overwrite が true でない限り拒否され、そこにシンボリックリンクがある場合は常に拒否されます。
vision_advice(path)	advice：ページごとに 1 つのエントリーがあり、needs_vision とその理由が含まれます。

すべての引数と結果において、ページ番号は 0 から始まります。confidence は、ブロックの種類を判定した学習済みモデルの確率です。モデルによる判定がない場合は null です。null は不明を意味し、低いことを意味するものではありません。

インストール

Python 3.10 以降と uv が必要です。初回使用時に uvx がサーバーと pdfluent をダウンロードし、キャッシュします。

uvx pdfluent-mcp --root ~/Documents

または、独自の環境にインストールします。

pip install pdfluent-mcp
pdfluent-mcp --root ~/Documents

許可するルート

サーバーは、指定されたルートの外には一切アクセスしません。--root（複数指定する場合は繰り返し指定）、PDFLUENT_MCP_ROOTS（Windows では : 区切り、; 区切り）でルートを指定するか、クライアントに提供させます。Claude Code は、作業ディレクトリと --add-dir で指定したディレクトリを MCP ルートとして送信します。これらのいずれからもルートが提供されない場合、サーバーはすべての呼び出しに対し、その旨を示すメッセージを返します。チェックの前にシンボリックリンクを解決するため、ルート内のリンクがルート外を指すことはできません。

ルートの範囲は、指定したディレクトリと同じです。クライアントが /、~、またはドライブ全体を MCP ルートとして提供すると、ユーザーが読み取れるすべてのものにサーバーがアクセスできるようになります。それを望まない場合は、PDF が保存されているフォルダーを --root で指定してサーバーを起動し、クライアントのルートも狭い範囲に保ってください。

さらに、次の 3 つの制限があります。--max-pages（デフォルトは 200）は、1 回の呼び出しで返すページ数です。長いドキュメントは pages を使って範囲ごとに読み取ります（エンジンは各範囲についてドキュメント全体を解析します。上限が制限するのは出力であり、処理量ではありません）。--max-bytes（デフォルトは 100 MiB）は、サーバーが開くドキュメントの最大サイズです。--max-output-chars（デフォルトは 200000）は、1 回の呼び出しで返す結果の最大文字数です。上限を超えると結果は切り詰められ、その旨が示されます。3 つの制限はそれぞれ PDFLUENT_MCP_MAX_PAGES、PDFLUENT_MCP_MAX_BYTES、PDFLUENT_MCP_MAX_OUTPUT_CHARS からも読み取られます。

以下の /path/to/documents は、PDF が保存されているディレクトリに置き換えてください。

Claude Desktop

claude_desktop_config.json に追加し（macOS： ~/Library/Application Support/Claude/claude_desktop_config.json、Windows： %APPDATA%\Claude\claude_desktop_config.json）、Claude Desktop を再起動します：

{
  "mcpServers": {
    "pdfluent": {
      "command": "uvx",
      "args": ["pdfluent-mcp", "--root", "/path/to/documents"]
    }
  }
}

Claude Desktop が uvx を見つけられない場合は、which uvx で確認したフルパスを command に記述してください。

Claude Code

claude mcp add pdfluent -- uvx pdfluent-mcp --root /path/to/documents

Claude Code は作業ディレクトリも MCP ルートとして提供するため、プロジェクト内では claude mcp add pdfluent -- uvx pdfluent-mcp だけで十分です。チームで使用する場合は、 プロジェクトの .mcp.json に次の内容を記述します：

{
  "mcpServers": {
    "pdfluent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pdfluent-mcp"]
    }
  }
}

これらのツールを使うタイミングを Claude に伝えるには、このリポジトリの skill/pdfluent を ~/.claude/skills/pdfluent（すべてのプロジェクト向け）または 1 つのプロジェクト内の .claude/skills/pdfluent にコピーします。

Cursor

Cursor に追加 （その後、/path/to/documents を変更します）。または、~/.cursor/mcp.json もしくは プロジェクトの .cursor/mcp.json に追加します：

{
  "mcpServers": {
    "pdfluent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pdfluent-mcp", "--root", "/path/to/documents"]
    }
  }
}

VS Code

VS Code にインストール、 またはターミナルから実行します：

code --add-mcp '{"name":"pdfluent","type":"stdio","command":"uvx","args":["pdfluent-mcp","--root","/path/to/documents"]}'

または、ワークスペースの .vscode/mcp.json に追加します（キーは servers です）：

{
  "servers": {
    "pdfluent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pdfluent-mcp", "--root", "/path/to/documents"]
    }
  }
}

Codex

~/.codex/config.toml に追加します：

[mcp_servers.pdfluent]
command = "uvx"
args = ["pdfluent-mcp", "--root", "/path/to/documents"]

開発

pip install -e ".[test]"
pytest

テストでは、実際の MCP クライアントを使って stdio 経由でサーバーを起動し、 tests/fixtures 内の PDF に対してすべてのツールを呼び出し、許可されたルートの外に 出ようとする操作も試します。

ライセンス

実行対象の pdfluent パッケージと同じライセンスです：AGPL-3.0-only、または PDFluent Commercial Licence。LICENSE と LICENSE-COMMERCIAL を参照してください。mcp（MIT）に 依存しています。