PDF to PNG Converter MCP

一個 MCP (Model Context Protocol) 服務器，讓 Claude Code 能夠：

• 將 PDF 檔案轉換為高品質 PNG 圖片（支援最高 1200 DPI）
• 從網路下載學術論文 PDF
• 根據期刊名稱和論文標題自動建立資料夾結構
• 下載論文後自動轉換為 PNG

功能特色

• 高品質轉換：支援 72-2400 DPI，預設 1200 DPI
• 智慧頁數保護：超過 10 頁的 PDF 預設僅保留 PDF，需確認後才轉換 PNG，避免意外大量轉換
• 批次處理：一次轉換整個資料夾的 PDF 檔案
• 自動整理：根據期刊和標題自動建立資料夾結構
• 多平台支援：Windows、macOS、Linux
• GUI 介面：提供獨立的圖形化介面（可選）

系統需求

• Python 3.10 或更高版本
• Poppler（用於 PDF 處理）

安裝 Poppler

Windows:

1. 下載 Poppler for Windows
2. 解壓縮到任意位置（例如 C:\poppler）
3. 將 bin 資料夾加入系統 PATH（例如 C:\poppler\bin）

macOS:

brew install poppler

Linux (Ubuntu/Debian):

sudo apt install poppler-utils

Claude Code Plugin 安裝

你可以直接從 marketplace 安裝為 Claude Code Plugin：

# Step 1: 加入 marketplace
/plugin marketplace add LostSunset/pdf_to_png_converter_mcp

# Step 2: 安裝 plugin
/plugin install pdf-to-png@pdf-to-png-marketplace

# 更新到最新版本
/plugin update pdf-to-png

安裝後可使用的 Skills：

• /pdf-to-png:convert-pdf — 將 PDF 轉換為 PNG
• /pdf-to-png:download-paper — 下載學術論文
• /pdf-to-png:search-paper — 搜尋 Semantic Scholar

安裝後 Claude 會自動透過 pdf-converter sub-agent 執行所有 PDF 相關任務，在獨立的上下文中自主完成檔案驗證、轉換、下載等工作流程。

快速安裝（推薦）

發布到 PyPI 後，只需一行指令即可在 Claude Code 中添加此 MCP：

# 使用 uvx（推薦）
claude mcp add pdf-to-png -- uvx pdf-to-png-converter-mcp

# 或使用 pipx
claude mcp add pdf-to-png -- pipx run pdf-to-png-converter-mcp

從源碼安裝

方法一：使用 uv（推薦）

# 克隆專案
git clone https://github.com/LostSunset/pdf_to_png_converter_mcp.git
cd pdf_to_png_converter_mcp

# 使用 uv 建立虛擬環境並安裝
uv venv .venv --python 3.12
uv pip install -e .

方法二：使用 pip

# 克隆專案
git clone https://github.com/LostSunset/pdf_to_png_converter_mcp.git
cd pdf_to_png_converter_mcp

# 建立虛擬環境並安裝
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# 或
.venv\Scripts\activate  # Windows

pip install -e .

在 Claude Code 中使用

設定 MCP 服務器

編輯 Claude Code 的設定檔（位於 ~/.claude/settings.json 或專案目錄下的 .claude/settings.json）：

{
  "mcpServers": {
    "pdf-to-png": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/pdf_to_png_converter_mcp",
        "pdf-to-png-mcp"
      ]
    }
  }
}

或使用 Python 直接執行：

{
  "mcpServers": {
    "pdf-to-png": {
      "command": "/path/to/pdf_to_png_converter_mcp/.venv314/Scripts/python.exe",
      "args": [
        "-m",
        "pdf_to_png_converter_mcp.server"
      ]
    }
  }
}

可用工具

安裝並設定完成後，Claude Code 將可以使用以下工具：

1. convert_pdf_to_png

將單個 PDF 檔案轉換為 PNG 圖片。超過 10 頁的 PDF 預設不轉換，僅保留 PDF。

參數：
- pdf_path (必填): PDF 檔案的完整路徑
- dpi (選填): 輸出解析度，預設 1200
- output_dir (選填): 輸出目錄，預設與 PDF 同目錄
- force_convert (選填): 超過 10 頁時是否強制轉換，預設 false

2. download_paper

從網路下載學術論文 PDF。

參數：
- url (必填): 論文 PDF 的下載網址
- journal (必填): 期刊名稱（用於建立資料夾）
- title (必填): 論文標題（用於命名檔案和資料夾）
- base_dir (選填): 基礎目錄，預設為當前目錄

3. download_and_convert

下載論文 PDF 並自動轉換為 PNG 圖片。超過 10 頁的 PDF 預設僅下載不轉換。

參數：
- url (必填): 論文 PDF 的下載網址
- journal (必填): 期刊名稱
- title (必填): 論文標題
- base_dir (選填): 基礎目錄
- dpi (選填): 輸出解析度，預設 1200
- force_convert (選填): 超過 10 頁時是否強制轉換，預設 false

4. batch_convert_pdfs

批次轉換資料夾中的所有 PDF 檔案。超過 10 頁的 PDF 預設會跳過。

參數：
- folder_path (必填): 包含 PDF 檔案的資料夾路徑
- dpi (選填): 輸出解析度，預設 1200
- recursive (選填): 是否遞迴搜尋子資料夾，預設 True
- force_convert (選填): 超過 10 頁時是否強制轉換，預設 false

5. search_paper

搜尋學術論文（使用 Semantic Scholar API）。

參數：
- query (必填): 搜尋關鍵字
- max_results (選填): 最大結果數量，預設 5，最大 20

使用範例

在 Claude Code 中，你可以這樣使用：

請幫我把 C:\Papers\paper.pdf 轉換成 PNG，使用 1200 DPI

請下載這篇論文並轉換成 PNG：
URL: https://example.com/paper.pdf
期刊: Nature
標題: Deep Learning for Image Recognition

請把 D:\Research\Papers 資料夾中的所有 PDF 都轉換成 PNG

GUI 介面

除了 MCP 服務器，本專案也提供獨立的 GUI 介面：

# 安裝 GUI 依賴
uv pip install -e ".[gui]" --python .venv314/Scripts/python.exe

# 啟動 GUI
pdf-to-png-gui

開發

安裝開發依賴

uv pip install -e ".[dev]" --python .venv314/Scripts/python.exe

執行測試

# 設定 UTF-8 編碼
set PYTHONIOENCODING=utf-8  # Windows
export PYTHONIOENCODING=utf-8  # macOS/Linux

# 執行測試
pytest

程式碼檢查

# 檢查並自動修復
ruff check --fix
ruff format

版本歷史

請參閱 CHANGELOG.md

授權

本專案採用 MIT 授權條款 - 詳見 LICENSE 檔案

Star History

---

Version: 0.4.0