ข้ามไปยังเนื้อหาหลัก
PPDF123

เซิร์ฟเวอร์ MCP ของ PDF123 สำหรับเอเจนต์ AI

MCP หรือ Model Context Protocol เป็นมาตรฐานเปิดที่ให้ไคลเอนต์ AI เช่น 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 แบบเดียวกัน

การตั้งค่าไคลเอนต์ MCPjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

รีสตาร์ตไคลเอนต์หลังเปลี่ยนการตั้งค่า หากต้องการเก็บสำเนาไว้ใน path ของคุณ ให้รัน npm install -g @pdf123/mcp ซึ่งให้คำสั่ง pdf123-mcp เซิร์ฟเวอร์ต้องใช้ Node 20.3 ขึ้นไปและต้องเข้าถึง API base ได้ ไม่มีโหมดออฟไลน์

ควรสั่งเอเจนต์อะไรเป็นอย่างแรก

สั่งด้วยภาษาธรรมดาและระบุชื่อไฟล์ เช่น

รวม ~/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 ของคุณเองแทน ดูโฮสต์เอง

ผลลัพธ์และข้อผิดพลาดมีหน้าตาอย่างไร

ผลลัพธ์เดียวเป็นออบเจ็กต์ 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 เป็นมาตรฐานเปิดสำหรับเชื่อมไคลเอนต์ AI กับเครื่องมือภายนอก ไคลเอนต์อย่าง Claude Code จะเริ่มหรือเชื่อมต่อกับเซิร์ฟเวอร์ MCP แสดงรายการเครื่องมือ และเรียกใช้แทนผู้ใช้

เซิร์ฟเวอร์ MCP ในเครื่องใช้งานแบบออฟไลน์ได้หรือไม่

ไม่ได้ เซิร์ฟเวอร์อัปโหลดไฟล์ไปยัง API ของ PDF123 หรือเซิร์ฟเวอร์ที่ระบุใน PDFX_API_BASE แล้วบันทึกผลลัพธ์ในเครื่อง จึงต้องเข้าถึง API base ได้

ต้องใช้คีย์ API หรือไม่

เซิร์ฟเวอร์ในเครื่องไม่ต้องใช้คีย์หากใช้แบบไม่ระบุตัวตน ตั้ง PDFX_API_KEY หากเซิร์ฟเวอร์ของคุณต้องใช้ ปลายทางที่โฮสต์ไว้ที่ /mcp ต้องมีเฮดเดอร์ X-API-KEY เสมอ

เอเจนต์อ่านไฟล์ใดก็ได้บนคอมพิวเตอร์ของฉันหรือไม่

โดยค่าเริ่มต้นอ่านได้ทุกเส้นทางที่โพรเซสของเซิร์ฟเวอร์เข้าถึงได้ ตั้ง PDFX_MCP_ROOT เพื่อจำกัดการอ่านและเขียนให้อยู่ในไดเรกทอรีที่คุณเลือก

ไฟล์ของฉันจะถูกจัดการอย่างไร

เซิร์ฟเวอร์ในเครื่องอัปโหลดแต่ละอินพุตไปยัง API ของ PDF123 หรือเซิร์ฟเวอร์ของคุณเองเพื่อประมวลผล คำอธิบายของเครื่องมือระบุว่าไฟล์จะถูกลบที่นั่นหลังประมวลผล ผลลัพธ์ถูกบันทึกบนเครื่องของคุณ ดูรายละเอียดได้ที่หน้าความเป็นส่วนตัวของไฟล์

เอเจนต์ใช้เครื่องมือได้กี่รายการ

เซิร์ฟเวอร์ในเครื่องเข้าถึงเครื่องมือทั้ง 97 รายการในแคตตาล็อกผ่านห้าเครื่องมือของ MCP ส่วนปลายทางที่โฮสต์ไว้จัดกลุ่มการทำงานตามหมวด (convert, pages, misc และ security) ไว้หลังเจ็ดเครื่องมือของ MCP