Lewati ke konten utama
PPDF123

Server MCP PDF123 untuk agen AI

MCP, Model Context Protocol, adalah standar terbuka yang memungkinkan klien AI seperti Claude Code, Claude Desktop, dan Cursor memanggil alat eksternal. PDF123 menyediakan server MCP lokal, @pdf123/mcp, untuk file di komputer Anda, serta endpoint yang di-host dan memakai kunci API.

@pdf123/mcpNode 20.3 atau lebih baru

Instalasi

npx -y @pdf123/mcp
Di halaman ini

Server MCP mana yang sebaiknya saya pakai?

Kedua server menyediakan operasi PDF123. Bedanya ada pada tempat berjalannya dan cara file sampai ke server.

Lokal: @pdf123/mcpHosted: /mcp
Berjalan diDi komputer Anda, dijalankan oleh klien MCP lewat stdioDi server PDF123 pada https://pdf123.xyz/mcp
MasukanJalur file di disk. Server mengunggahnya dan menyimpan hasil di samping file masukanFile yang dikirim lewat alat unggah
KredensialTidak ada untuk pemakaian anonim. PDFX_API_KEY bersifat opsionalHeader X-API-KEY pada setiap permintaan. Tanpa header itu jawabannya 401
Instalasinpx -y @pdf123/mcpTidak perlu. Tambahkan URL dan header ke klien
AlatLima alat untuk seluruh katalog 97 alatTujuh alat: describe, convert, pages, misc, security, upload, dan download
Pakai jikaAgen mengerjakan dokumen di folder lokalAgen atau layanan hosted sudah menangani unggahan lewat API

Pakai server lokal untuk asisten pemrograman di laptop. Pakai endpoint hosted jika agen berjalan di cloud dan tidak bisa membaca disk Anda.

Bagaimana cara memasang server MCP lokal?

Tidak ada yang perlu dipasang, karena klien MCP menjalankan server dengan npx. Di Claude Code, tambahkan dengan satu perintah.

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

Claude Desktop membaca claude_desktop_config.json, dan Cursor membaca .cursor/mcp.json. Klien lain punya halaman atau file pengaturan MCP. Semuanya menerima entri mcpServers yang sama.

MCP client configurationjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

Mulai ulang klien setelah Anda mengubah konfigurasinya. Untuk menyimpan salinan di path Anda, jalankan npm install -g @pdf123/mcp, yang menyediakan perintah pdf123-mcp. Server membutuhkan Node 20.3 atau lebih baru dan basis API yang dapat dijangkau. Tidak ada mode offline.

Apa yang pertama kali saya minta kepada agen?

Minta dengan bahasa sehari-hari dan sebutkan file-nya. Contohnya:

Gabungkan ~/Documents/a.pdf dan ~/Documents/b.pdf, lalu kompres hasilnya.

Agen memanggil pdf123_run_pipeline, atau pdf123_run_tool dua kali, mengunggah file ke PDF123, dan menjawab dengan jalur file yang tersimpan. Hasil disimpan di samping masukan pertama dan tidak pernah menimpa file yang sudah ada. Operasi yang sama tersedia sebagai Gabungkan dan Kompres di situs web.

Alat apa saja yang disediakan server lokal?

Server memiliki lima alat. Id alat seperti merge adalah argumen string biasa, sehingga daftar alatnya tetap ringkas.

AlatFungsinyaArgumen utama
pdf123_list_toolsMencantumkan alat, satu baris untuk tiap alatgroup, query, format
pdf123_describe_toolMenampilkan kolom alat, nilai bawaan, nilai yang diizinkan, dan apakah alat berjalan sebagai batchtool
pdf123_run_toolMenjalankan satu alat pada file lokal dan mengembalikan jalur file tersimpan atau laporan JSONtool, files, params, output
pdf123_run_pipelineMerangkai hingga 8 alat dalam satu permintaansteps, files, output
pdf123_callMengirim permintaan mentah ke id alat, id operasi, atau jalur /api/... apa puntarget, files, fields

Agen biasanya memanggil pdf123_list_tools untuk menemukan alat, pdf123_describe_tool untuk membaca kolomnya, lalu pdf123_run_tool. Id yang salah ketik mengembalikan saran "maksud Anda".

Bagaimana batch, kata sandi, dan pipeline bekerja?

  • Batch. Beberapa file yang diberikan ke alat satu-file dijalankan sebagai batch dengan satu hasil untuk tiap file. Setiap file disimpan begitu selesai. Balasannya berupa laporan per file. Jika ada file yang gagal, balasannya berupa galat dengan laporan terlampir, sehingga agen dapat mengulang hanya file yang gagal.
  • Kata sandi. input_password membuka semua masukan terenkripsi. passwords menetapkan satu kata sandi per file, dengan urutan yang sama seperti files, memakai string kosong untuk file yang terbuka. Ini juga berlaku untuk alat multi-file seperti Gabungkan.
  • Pipeline. pdf123_run_pipeline menerima hingga 8 langkah, dan setiap langkah memberi masukan ke langkah berikutnya. Argumen kata sandinya sama.
  • Panggilan mentah. pdf123_call menjangkau operasi yang lebih baru daripada server. Tidak ada yang divalidasi secara lokal.
  • Alat filter. Alat yang id-nya diawali filter- menjawab {"matched": false} jika kondisinya tidak terpenuhi. Itu adalah hasil, bukan galat.
  • Pengulangan. idempotencyKey memutar ulang hasil pertama selama 24 jam.

Bagaimana cara membatasi folder yang boleh dipakai agen?

Setel PDFX_MCP_ROOT ke sebuah direktori. Pisahkan beberapa direktori dengan titik dua, atau titik koma di Windows. Server kemudian hanya membaca masukan dan menulis hasil di dalam direktori tersebut. Jalur di luarnya, pelarian dengan .., dan symbolic link yang mengarah keluar ditolak sebelum apa pun diunggah, dengan Code: path_not_allowed. Tanpa variabel ini, jalur apa pun yang dapat dijangkau proses server diizinkan.

Restrict file accessjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

Setel variabel lingkungan di blok env klien, atau dengan claude mcp add -e NAME=value. PDFX_API_BASE mengarahkan server ke pdfx-server Anda sendiri; lihat Self-host.

Seperti apa hasil dan galatnya?

Satu hasil berupa objek JSON kecil dengan path file tersimpan, contentType, dan ukuran dalam bytes. Hasil batch memiliki processed, unmatched, failed, dan daftar files. Bentuk ini sama dengan pdfx --json di baris perintah. Alat yang mengembalikan laporan, seperti Informasi dokumen, mengembalikan laporannya secara langsung.

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

Panggilan yang gagal kembali sebagai galat alat. Teksnya diakhiri baris Reason:, Code:, dan Hint: jika server menyediakannya, sehingga agen dapat bercabang berdasarkan kode.

Error texttext
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.

Jika id alat salah ketik, galat mencantumkan id yang mirip dan diakhiri Code: unknown_tool. Alat yang tidak menemukan apa pun untuk dikembalikan, seperti pdf-to-csv pada PDF tanpa tabel, mengembalikan Code: no_content alih-alih file kosong. Lihat Kode galat.

Bagaimana cara memakai endpoint MCP yang di-host?

API menanamkan server MCP di POST https://pdf123.xyz/mcp. Lakukan autentikasi dengan header X-API-KEY yang sama seperti pada REST API. Tanpa kunci, endpoint menjawab 401. Buat kunci di halaman Pengembang.

Hosted endpoint configurationjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

Server hosted menyediakan tujuh alat: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload, dan pdf_toolbox_download. Setiap alat kategori menerima nama operation beserta parameternya, ditambah sebuah file atau fileId yang dikembalikan oleh alat unggah. Gunakan alat describe untuk mendapatkan skema satu operasi.

FAQ

Apa itu MCP?

MCP, Model Context Protocol, adalah standar terbuka untuk menghubungkan klien AI ke alat eksternal. Klien seperti Claude Code menjalankan atau menghubungi server MCP, mendaftar alatnya, lalu memanggilnya atas nama pengguna.

Apakah server MCP lokal bisa bekerja offline?

Tidak. Server ini mengunggah file ke API PDF123, atau ke server yang disebut di PDFX_API_BASE, lalu menyimpan hasilnya secara lokal. Basis API harus dapat dijangkau.

Apakah perlu kunci API?

Server lokal tidak memerlukan kunci untuk pemakaian anonim. Setel PDFX_API_KEY jika server Anda mewajibkannya. Endpoint hosted di /mcp selalu memerlukan header X-API-KEY.

Bisakah agen membaca file apa pun di komputer saya?

Secara bawaan agen dapat membaca jalur apa pun yang dapat dijangkau proses server. Setel PDFX_MCP_ROOT untuk membatasi pembacaan dan penulisan pada direktori yang Anda pilih.

Apa yang terjadi pada file saya?

Server lokal mengunggah setiap masukan ke API PDF123, atau ke server Anda sendiri, untuk diproses. Deskripsi alat menyatakan bahwa file dihapus di sana setelah pemrosesan. Hasilnya disimpan di komputer Anda. Untuk detailnya, baca halaman privasi file.

Berapa banyak alat yang dapat dipakai agen?

Server lokal menjangkau seluruh 97 alat dalam katalog lewat lima alat MCP. Endpoint hosted mengelompokkan operasinya menurut kategori (convert, pages, misc, dan security) di balik tujuh alat MCP.