Перейти к основному содержимому
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"]
    }
  }
}

После изменения конфигурации перезапустите клиент. Чтобы сохранить копию в системном пути, выполните npm install -g @pdf123/mcp: появится команда pdf123-mcp. Серверу нужен Node 20.3 или новее и доступный базовый адрес API. Автономного режима нет.

Что попросить у агента в первую очередь?

Пишите обычным языком и называйте файлы. Например:

Объедини ~/Documents/a.pdf и ~/Documents/b.pdf, а затем сожми результат.

Агент вызывает pdf123_run_pipeline или дважды pdf123_run_tool, загружает файлы в PDF123 и отвечает путём к сохранённому файлу. Результат сохраняется рядом с первым входным файлом и никогда не заменяет существующий файл. Те же операции есть на сайте как Объединить и Сжать.

Какие инструменты предлагает локальный сервер?

У сервера пять инструментов. Идентификаторы вроде 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.

Вопросы и ответы

Что такое 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.