Перейти до основного вмісту
PPDF123

MCP-сервери PDF123 для ШІ-агентів

MCP, Model Context Protocol, — це відкритий стандарт, який дає змогу ШІ-клієнтам, як-от Claude Code, Claude Desktop і Cursor, викликати зовнішні інструменти. PDF123 пропонує локальний MCP-сервер @pdf123/mcp для файлів на вашому комп’ютері та хостингову кінцеву точку, що працює з ключем API.

@pdf123/mcpNode 20.3 або новіша версія

Установлення

npx -y @pdf123/mcp
На цій сторінці

Який MCP-сервер обрати?

Обидва сервери надають операції PDF123. Вони відрізняються тим, де працюють і як до них потрапляють файли.

Локальний: @pdf123/mcpХостинговий: /mcp
Де працюєНа вашому комп’ютері; MCP-клієнт запускає його через stdioНа серверах PDF123 за адресою https://pdf123.xyz/mcp
Вхідні даніШляхи до файлів на диску. Сервер завантажує їх і зберігає результат поруч із вхідним файломФайли, надіслані через інструмент завантаження
Облікові даніДля анонімного використання не потрібні. PDFX_API_KEY необов’язковийЗаголовок X-API-KEY у кожному запиті. Без нього відповідь 401
Установленняnpx -y @pdf123/mcpНе потрібне. Додайте в клієнт URL і заголовок
ІнструментиП’ять інструментів для всього каталогу з 97 інструментівСім інструментів: describe, convert, pages, misc, security, upload і download
Коли використовуватиАгент працює з документами в локальній теціАгент або хостингова служба вже обробляє завантаження через API

Для асистентів із програмування на ноутбуці беріть локальний сервер. Хостингову кінцеву точку беріть, коли агент працює в хмарі й не може читати ваш диск.

Як установити локальний MCP-сервер?

Нічого встановлювати не потрібно, бо MCP-клієнт запускає сервер через npx. У Claude Code додайте його однією командою.

Claude Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

Claude Desktop читає claude_desktop_config.json, а Cursor — .cursor/mcp.json. В інших клієнтів є сторінка чи файл налаштувань MCP. Усі вони приймають той самий запис mcpServers.

Конфігурація MCP-клієнтаjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

Після зміни конфігурації перезапустіть клієнт. Щоб мати команду під рукою в PATH, виконайте npm install -g @pdf123/mcp, що додає команду pdf123-mcp. Серверу потрібні Node 20.3 або новіша версія та доступна базова адреса API. Автономного режиму немає.

Що спитати в агента спочатку?

Пишіть звичайною мовою й називайте файли. Наприклад:

Об’єднай ~/Documents/a.pdf і ~/Documents/b.pdf, а потім стисни результат.

Агент викликає pdf123_run_pipeline або двічі pdf123_run_tool, завантажує файли до PDF123 і відповідає шляхом до збереженого файла. Результат зберігається поруч із першим вхідним файлом і ніколи не перезаписує наявний. Ті самі операції на сайті доступні як Об’єднати PDF і Стиснути PDF.

Які інструменти пропонує локальний сервер?

У сервера п’ять інструментів. Ідентифікатори інструментів, як-от merge, — це звичайні рядкові аргументи, тож перелік інструментів залишається коротким.

ІнструментЩо робитьОсновні аргументи
pdf123_list_toolsПерелічує інструменти, по одному рядку на коженgroup, query, format
pdf123_describe_toolПоказує поля інструмента, типові та допустимі значення й чи працює він пакетноtool
pdf123_run_toolЗапускає один інструмент для локальних файлів і повертає збережений шлях або звіт JSONtool, files, params, output
pdf123_run_pipelineПоєднує до 8 інструментів в одному запитіsteps, files, output
pdf123_callНадсилає сирий запит до будь-якого ідентифікатора інструмента, ідентифікатора операції або шляху /api/...target, files, fields

Зазвичай агент викликає pdf123_list_tools, щоб знайти інструмент, pdf123_describe_tool, щоб прочитати його поля, а потім pdf123_run_tool. Помилково введений ідентифікатор повертає підказки «можливо, ви мали на увазі».

Як працюють пакети, паролі й конвеєри?

  • Пакети. Кілька файлів, передані інструменту для одного файла, обробляються пакетом з окремим результатом для кожного. Кожен файл зберігається, щойно його оброблено. Відповідь — звіт по кожному файлу. Якщо хоч один файл не вдався, відповідь — це помилка зі звітом у додатку, тож агент може повторити лише невдалі файли.
  • Паролі. input_password відкриває кожен зашифрований вхідний файл. passwords задає по одному паролю на файл у тому самому порядку, що й files, а для відкритого файла — порожній рядок. Це працює й для інструментів із кількома файлами, як-от Об’єднати.
  • Конвеєри. pdf123_run_pipeline приймає до 8 кроків, і кожен крок живить наступний. Він приймає ті самі аргументи паролів.
  • Сирі виклики. pdf123_call дає доступ до операцій, новіших за сервер. Локально нічого не перевіряється.
  • Інструменти-фільтри. Інструмент, ідентифікатор якого починається з filter-, відповідає {"matched": false}, коли його умова не виконується. Це результат, а не помилка.
  • Повторні спроби. idempotencyKey повертає перший результат протягом 24 годин.

Як обмежити теки, доступні агентові?

Задайте для PDFX_MCP_ROOT каталог. Кілька каталогів розділяйте двокрапкою, а в Windows — крапкою з комою. Тоді сервер читає вхідні дані й записує результати лише всередині цих каталогів. Шляхи поза ними, вихід через .. і символічні посилання назовні відхиляються до будь-якого завантаження з Code: path_not_allowed. Без цієї змінної дозволено будь-який шлях, до якого має доступ процес сервера.

Обмеження доступу до файлівjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

Змінні середовища задавайте в блоці env клієнта або через claude mcp add -e NAME=value. PDFX_API_BASE спрямовує сервер на ваш власний pdfx-server; див. Self-host.

Як виглядають результати й помилки?

Один результат — це невеликий об’єкт JSON зі збереженим path, contentType і розміром у bytes. Результат пакета містить processed, unmatched, failed і список files. Ці структури збігаються з виводом pdfx --json у командному рядку. Інструмент, що повертає звіт, як-от Відомості про документ, повертає звіт безпосередньо у відповіді.

Один результатjson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

Невдалий виклик повертається як помилка інструмента. Її текст закінчується рядками Reason:, Code: і Hint:, якщо їх надав сервер, тож агент може розгалужуватися за кодом.

Текст помилкиtext
HTTP 400: This PDF is password-protected. Enter its password.
Reason: password_required
Code: bad_request
Hint: Provide the document password, or unlock the PDF first.

Якщо в ідентифікаторі інструмента друкарська помилка, у повідомленні перелічено схожі ідентифікатори, і воно закінчується Code: unknown_tool. Інструмент, якому нічого повертати, наприклад pdf-to-csv для PDF без таблиць, повертає Code: no_content замість порожнього файла. Див. Коди помилок.

Як користуватися хостинговою кінцевою точкою MCP?

API вбудовує MCP-сервер за адресою POST https://pdf123.xyz/mcp. Автентифікуйтеся тим самим заголовком X-API-KEY, що й у REST API. Без ключа кінцева точка відповідає 401. Створіть ключ на сторінці для розробників.

Конфігурація хостингової кінцевої точкиjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

Хостинговий сервер надає сім інструментів: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload і pdf_toolbox_download. Кожен інструмент категорії приймає назву operation і її параметри, а також файл або fileId, який повернув інструмент завантаження. Схему однієї операції можна отримати за допомогою інструмента describe.

FAQ

Що таке MCP?

MCP, Model Context Protocol, — це відкритий стандарт для підключення ШІ-клієнтів до зовнішніх інструментів. Клієнт, як-от Claude Code, запускає MCP-сервер або звертається до нього, отримує перелік його інструментів і викликає їх від імені користувача.

Чи працює локальний MCP-сервер офлайн?

Ні. Він завантажує файли до API PDF123 або на сервер, указаний у PDFX_API_BASE, і зберігає результат локально. Базова адреса API має бути доступною.

Чи потрібен ключ API?

Локальному серверу ключ для анонімного використання не потрібен. Задайте PDFX_API_KEY, якщо ваш сервер його вимагає. Хостингова кінцева точка /mcp завжди потребує заголовка X-API-KEY.

Чи може агент прочитати будь-який файл на моєму комп’ютері?

За замовчуванням він може читати будь-який шлях, до якого має доступ процес сервера. Задайте PDFX_MCP_ROOT, щоб обмежити читання й запис обраними вами каталогами.

Що відбувається з моїми файлами?

Локальний сервер завантажує кожен вхідний файл до API PDF123 або на ваш власний сервер для обробки. В описі інструмента сказано, що після обробки файли там видаляються. Результат зберігається на вашому комп’ютері. Подробиці читайте на сторінці про приватність файлів.

Скільки інструментів може використовувати агент?

Локальний сервер надає доступ до всіх 97 інструментів каталогу через п’ять інструментів MCP. Хостингова кінцева точка групує операції за категоріями (convert, pages, misc і security) за сімома інструментами MCP.