Przejdź do głównej treści
PPDF123

Serwery MCP PDF123 dla agentów AI

MCP, czyli Model Context Protocol, to otwarty standard, dzięki któremu klienty AI, takie jak Claude Code, Claude Desktop i Cursor, mogą wywoływać zewnętrzne narzędzia. PDF123 oferuje lokalny serwer MCP, @pdf123/mcp, dla plików na Twoim komputerze oraz hostowany endpoint używający klucza API.

@pdf123/mcpNode 20.3 lub nowszy

Instalacja

npx -y @pdf123/mcp
Na tej stronie

Którego serwera MCP użyć?

Oba serwery udostępniają operacje PDF123. Różnią się tym, gdzie działają i w jaki sposób trafiają do nich pliki.

Lokalny: @pdf123/mcpHostowany: /mcp
Gdzie działaNa Twoim komputerze, uruchamiany przez klienta MCP przez stdioNa serwerach PDF123 pod adresem https://pdf123.xyz/mcp
WejścieŚcieżki plików na dysku. Serwer przesyła je i zapisuje wynik obok pliku wejściowegoPliki wysyłane przez narzędzie przesyłania
PoświadczeniaBrak przy użyciu anonimowym. PDFX_API_KEY jest opcjonalnyNagłówek X-API-KEY w każdym żądaniu. Bez niego odpowiedź to 401
Instalacjanpx -y @pdf123/mcpNic. Dodaj adres URL i nagłówek w kliencie
NarzędziaPięć narzędzi obejmujących cały katalog 97 narzędziSiedem narzędzi: describe, convert, pages, misc, security, upload i download
Kiedy użyćAgent pracuje na dokumentach w lokalnym folderzeAgent lub usługa hostowana już obsługuje przesyłanie plików przez API

Lokalny serwer wybierz dla asystentów programistycznych na laptopie. Hostowany endpoint wybierz wtedy, gdy agent działa w chmurze i nie może czytać Twojego dysku.

Jak zainstalować lokalny serwer MCP?

Nic nie trzeba instalować, ponieważ klient MCP uruchamia serwer przez npx. W Claude Code dodasz go jednym poleceniem.

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

Claude Desktop czyta claude_desktop_config.json, a Cursor czyta .cursor/mcp.json. Inne klienty mają stronę lub plik ustawień MCP. Wszystkie akceptują ten sam wpis mcpServers.

Konfiguracja klienta MCPjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

Po zmianie konfiguracji uruchom klienta ponownie. Aby mieć kopię w ścieżce systemowej, uruchom npm install -g @pdf123/mcp, co udostępnia polecenie pdf123-mcp. Serwer wymaga Node 20.3 lub nowszego oraz osiągalnego adresu bazowego API. Nie ma trybu offline.

O co poprosić agenta na początek?

Pisz zwykłym językiem i podaj nazwy plików. Na przykład:

Połącz ~/Documents/a.pdf i ~/Documents/b.pdf, a potem skompresuj wynik.

Agent wywołuje pdf123_run_pipeline albo dwa razy pdf123_run_tool, przesyła pliki do PDF123 i odpowiada ścieżką zapisanego pliku. Wynik jest zapisywany obok pierwszego pliku wejściowego i nigdy nie zastępuje istniejącego pliku. Te same operacje są dostępne w serwisie jako Połącz i Kompresuj.

Jakie narzędzia oferuje lokalny serwer?

Serwer ma pięć narzędzi. Identyfikatory narzędzi, takie jak merge, są zwykłymi argumentami tekstowymi, dzięki czemu lista narzędzi pozostaje krótka.

NarzędzieCo robiKluczowe argumenty
pdf123_list_toolsWypisuje narzędzia, po jednej linii na narzędziegroup, query, format
pdf123_describe_toolPokazuje pola narzędzia, wartości domyślne, dozwolone wartości i informację, czy działa jako partiatool
pdf123_run_toolUruchamia jedno narzędzie na plikach lokalnych i zwraca zapisaną ścieżkę lub raport JSONtool, files, params, output
pdf123_run_pipelineŁączy do 8 narzędzi w jednym żądaniusteps, files, output
pdf123_callWysyła surowe żądanie do dowolnego identyfikatora narzędzia, identyfikatora operacji lub ścieżki /api/...target, files, fields

Agent zwykle wywołuje pdf123_list_tools, aby znaleźć narzędzie, pdf123_describe_tool, aby przeczytać jego pola, a następnie pdf123_run_tool. Literówka w identyfikatorze zwraca podpowiedzi „czy chodziło o”.

Jak działają partie, hasła i potoki?

  • Partie. Kilka plików podanych narzędziu jednoplikowemu jest uruchamianych jako partia z jednym wynikiem na plik. Każdy plik jest zapisywany, gdy tylko zostanie przetworzony. Odpowiedź to raport dla każdego pliku. Jeśli którykolwiek plik się nie powiedzie, odpowiedzią jest błąd z dołączonym raportem, dzięki czemu agent może ponowić tylko nieudane pliki.
  • Hasła. input_password otwiera każde zaszyfrowane wejście. passwords ustawia jedno hasło na plik, w tej samej kolejności co files, z pustym ciągiem dla pliku otwartego. Działa to także dla narzędzi wieloplikowych, takich jak Połącz.
  • Potoki. pdf123_run_pipeline przyjmuje do 8 kroków, a każdy krok zasila następny. Przyjmuje te same argumenty haseł.
  • Wywołania surowe. pdf123_call sięga po operacje nowsze niż serwer. Lokalnie nic nie jest walidowane.
  • Narzędzia filtrujące. Narzędzie, którego identyfikator zaczyna się od filter-, odpowiada {"matched": false}, gdy jego warunek nie jest spełniony. To wynik, a nie błąd.
  • Ponawianie. idempotencyKey zwraca pierwszy wynik przez 24 godziny.

Jak ograniczyć, z których folderów może korzystać agent?

Ustaw PDFX_MCP_ROOT na katalog. Kilka katalogów rozdziel dwukropkiem, a w systemie Windows średnikiem. Serwer czyta wtedy wejścia i zapisuje wyniki tylko w tych katalogach. Ścieżki spoza nich, wyjścia przez .. i dowiązania symboliczne prowadzące na zewnątrz są odrzucane, zanim cokolwiek zostanie wysłane, z Code: path_not_allowed. Bez tej zmiennej dozwolona jest każda ścieżka, do której ma dostęp proces serwera.

Ograniczenie dostępu do plikówjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

Zmienne środowiskowe ustaw w bloku env klienta lub przez claude mcp add -e NAME=value. PDFX_API_BASE kieruje serwer na Twój własny pdfx-server; zobacz Self-host.

Jak wyglądają wyniki i błędy?

Pojedynczy wynik to mały obiekt JSON z zapisaną ścieżką path, typem contentType i rozmiarem w bytes. Wynik partii zawiera processed, unmatched, failed oraz listę files. Te kształty odpowiadają pdfx --json w wierszu poleceń. Narzędzie zwracające raport, takie jak Informacje o dokumencie, zwraca raport bezpośrednio w odpowiedzi.

Pojedynczy wynikjson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

Nieudane wywołanie wraca jako błąd narzędzia. Jego tekst kończy się liniami Reason:, Code: i Hint:, jeśli serwer je podał, więc agent może rozgałęziać logikę według kodu.

Tekst błędutext
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.

Jeśli w identyfikatorze narzędzia jest literówka, błąd wymienia zbliżone identyfikatory i kończy się Code: unknown_tool. Narzędzie, które nie ma nic do zwrócenia, na przykład pdf-to-csv dla PDF-a bez tabel, zwraca Code: no_content zamiast pustego pliku. Zobacz Kody błędów.

Jak używać hostowanego endpointu MCP?

API zawiera wbudowany serwer MCP pod adresem POST https://pdf123.xyz/mcp. Uwierzytelnij się tym samym nagłówkiem X-API-KEY, którego używa API REST. Bez klucza endpoint odpowiada 401. Klucz utworzysz na stronie dla deweloperów.

Konfiguracja hostowanego endpointujson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

Hostowany serwer udostępnia siedem narzędzi: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload i pdf_toolbox_download. Każde narzędzie kategorii przyjmuje nazwę operation i jej parametry oraz plik lub fileId zwrócony przez narzędzie przesyłania. Schemat jednej operacji pobierzesz narzędziem describe.

FAQ

Czym jest MCP?

MCP, czyli Model Context Protocol, to otwarty standard łączenia klientów AI z zewnętrznymi narzędziami. Klient, taki jak Claude Code, uruchamia serwer MCP lub łączy się z nim, pobiera listę jego narzędzi i wywołuje je w imieniu użytkownika.

Czy lokalny serwer MCP działa offline?

Nie. Przesyła pliki do API PDF123 lub na serwer wskazany w PDFX_API_BASE i zapisuje wynik lokalnie. Adres bazowy API musi być osiągalny.

Czy potrzebuje klucza API?

Lokalny serwer nie wymaga klucza przy użyciu anonimowym. Ustaw PDFX_API_KEY, jeśli Twój serwer tego wymaga. Hostowany endpoint pod /mcp zawsze wymaga nagłówka X-API-KEY.

Czy agent może czytać dowolny plik na moim komputerze?

Domyślnie może czytać każdą ścieżkę, do której ma dostęp proces serwera. Ustaw PDFX_MCP_ROOT, aby ograniczyć odczyt i zapis do wybranych katalogów.

Co się dzieje z moimi plikami?

Lokalny serwer przesyła każde wejście do API PDF123 lub na Twój własny serwer w celu przetworzenia. Opis narzędzia podaje, że pliki są tam usuwane po przetworzeniu. Wynik jest zapisywany na Twoim komputerze. Szczegóły znajdziesz na stronie o prywatności plików.

Ile narzędzi może używać agent?

Lokalny serwer udostępnia wszystkie 97 narzędzi z katalogu przez pięć narzędzi MCP. Hostowany endpoint grupuje swoje operacje według kategorii (convert, pages, misc i security) za siedmioma narzędziami MCP.