Chuyển đến nội dung chính
PPDF123

Máy chủ MCP của PDF123 cho AI agent

MCP, tức Model Context Protocol, là chuẩn mở cho phép các ứng dụng AI như Claude Code, Claude Desktop và Cursor gọi công cụ bên ngoài. PDF123 cung cấp máy chủ MCP cục bộ @pdf123/mcp cho tệp trên máy bạn và một endpoint lưu trữ sẵn dùng khóa API.

@pdf123/mcpNode 20.3 trở lên

Cài đặt

npx -y @pdf123/mcp
Trên trang này

Nên dùng máy chủ MCP nào?

Cả hai máy chủ đều cung cấp các thao tác của PDF123. Chúng khác nhau ở nơi chạy và cách tệp đến được máy chủ.

Cục bộ: @pdf123/mcpLưu trữ sẵn: /mcp
Chạy ở đâuTrên máy bạn, do ứng dụng MCP khởi chạy qua stdioTrên máy chủ của PDF123 tại https://pdf123.xyz/mcp
Đầu vàoĐường dẫn tệp trên ổ đĩa. Máy chủ tải chúng lên và lưu kết quả cạnh tệp đầu vàoTệp gửi qua công cụ tải lên
Thông tin xác thựcKhông cần khi dùng ẩn danh. PDFX_API_KEY là tùy chọnHeader X-API-KEY trong mọi yêu cầu. Thiếu header thì trả 401
Cài đặtnpx -y @pdf123/mcpKhông cần. Thêm URL và header vào ứng dụng
Công cụNăm công cụ cho toàn bộ danh mục 97 công cụBảy công cụ: describe, convert, pages, misc, security, upload và download
Dùng khiAgent làm việc với tài liệu trong một thư mục cục bộAgent hoặc dịch vụ lưu trữ sẵn đã xử lý việc tải lên qua API

Hãy dùng máy chủ cục bộ cho trợ lý lập trình trên laptop. Dùng endpoint lưu trữ sẵn khi agent chạy trên đám mây và không đọc được ổ đĩa của bạn.

Làm sao cài máy chủ MCP cục bộ?

Không cần cài gì cả, vì ứng dụng MCP khởi chạy máy chủ bằng npx. Trong Claude Code, thêm nó bằng một lệnh.

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

Claude Desktop đọc claude_desktop_config.json, còn Cursor đọc .cursor/mcp.json. Các ứng dụng khác có trang hoặc tệp cài đặt MCP. Tất cả đều chấp nhận cùng một mục mcpServers.

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

Hãy khởi động lại ứng dụng sau khi thay đổi cấu hình. Để giữ một bản trong đường dẫn của bạn, chạy npm install -g @pdf123/mcp, lệnh này cung cấp lệnh pdf123-mcp. Máy chủ cần Node 20.3 trở lên và một API base truy cập được. Không có chế độ ngoại tuyến.

Nên yêu cầu agent điều gì trước tiên?

Hãy hỏi bằng ngôn ngữ thường ngày và nêu tên các tệp. Ví dụ:

Gộp ~/Documents/a.pdf và ~/Documents/b.pdf, rồi nén kết quả.

Agent gọi pdf123_run_pipeline, hoặc gọi pdf123_run_tool hai lần, tải các tệp lên PDF123 và trả lời bằng đường dẫn của tệp đã lưu. Kết quả được lưu cạnh tệp đầu vào đầu tiên và không bao giờ thay thế tệp đã có. Các thao tác tương tự có trên website với tên Gộp và Nén.

Máy chủ cục bộ cung cấp những công cụ nào?

Máy chủ có năm công cụ. Các id công cụ như merge chỉ là đối số chuỗi thông thường, nên danh sách công cụ luôn gọn.

Công cụChức năngĐối số chính
pdf123_list_toolsLiệt kê các công cụ, mỗi công cụ một dònggroup, query, format
pdf123_describe_toolCho thấy các trường, giá trị mặc định, giá trị cho phép của một công cụ và việc nó có chạy theo lô hay khôngtool
pdf123_run_toolChạy một công cụ trên tệp cục bộ và trả về đường dẫn đã lưu hoặc báo cáo JSONtool, files, params, output
pdf123_run_pipelineNối tối đa 8 công cụ trong một yêu cầusteps, files, output
pdf123_callGửi yêu cầu thô tới bất kỳ id công cụ, id thao tác hoặc đường dẫn /api/... nàotarget, files, fields

Agent thường gọi pdf123_list_tools để tìm công cụ, pdf123_describe_tool để đọc các trường của nó, rồi mới gọi pdf123_run_tool. Id gõ sai sẽ nhận gợi ý "ý bạn là".

Xử lý hàng loạt, mật khẩu và pipeline hoạt động thế nào?

  • Lô. Nhiều tệp đưa cho công cụ một tệp sẽ chạy theo lô, mỗi tệp một kết quả. Mỗi tệp được lưu ngay khi xong. Phản hồi là báo cáo theo từng tệp. Nếu có tệp nào lỗi, phản hồi là một lỗi kèm báo cáo, để agent chỉ thử lại các tệp đã lỗi.
  • Mật khẩu. input_password mở mọi đầu vào đã mã hóa. passwords đặt một mật khẩu cho mỗi tệp, theo cùng thứ tự với files, dùng chuỗi rỗng cho tệp không có mật khẩu. Cách này cũng dùng được cho các công cụ nhiều tệp như Gộp.
  • Pipeline. pdf123_run_pipeline nhận tối đa 8 bước, và mỗi bước đưa đầu ra cho bước kế tiếp. Nó nhận cùng các đối số mật khẩu.
  • Gọi thô. pdf123_call truy cập các thao tác mới hơn máy chủ. Không có gì được kiểm tra ở phía cục bộ.
  • Công cụ lọc. Công cụ có id bắt đầu bằng filter- trả về {"matched": false} khi điều kiện không thỏa. Đó là một kết quả, không phải lỗi.
  • Thử lại. idempotencyKey phát lại kết quả đầu tiên trong 24 giờ.

Làm sao giới hạn thư mục mà agent được dùng?

Đặt PDFX_MCP_ROOT là một thư mục. Ngăn cách nhiều thư mục bằng dấu hai chấm, hoặc dấu chấm phẩy trên Windows. Khi đó máy chủ chỉ đọc đầu vào và ghi kết quả trong các thư mục này. Đường dẫn nằm ngoài, các cách thoát bằng .. và liên kết tượng trưng dẫn ra ngoài đều bị từ chối trước khi có gì được tải lên, với Code: path_not_allowed. Nếu không đặt biến này, mọi đường dẫn mà tiến trình máy chủ truy cập được đều được phép.

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

Hãy đặt biến môi trường trong khối env của ứng dụng, hoặc bằng claude mcp add -e NAME=value. PDFX_API_BASE trỏ máy chủ tới pdfx-server của riêng bạn; xem Tự host.

Kết quả và lỗi trông như thế nào?

Một kết quả đơn là một đối tượng JSON nhỏ gồm path đã lưu, contentType và dung lượng bytes. Kết quả của lô có processed, unmatched, failed và danh sách files. Các dạng này khớp với pdfx --json trên dòng lệnh. Công cụ trả về báo cáo, chẳng hạn Thông tin tài liệu, trả báo cáo ngay trong phản hồi.

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

Lời gọi thất bại được trả về dưới dạng lỗi công cụ. Văn bản của nó kết thúc bằng các dòng Reason:, Code: và Hint: nếu máy chủ cung cấp, để agent rẽ nhánh theo mã.

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.

Nếu id công cụ bị gõ sai, lỗi sẽ liệt kê các id gần giống và kết thúc bằng Code: unknown_tool. Công cụ không tìm thấy gì để trả về, chẳng hạn pdf-to-csv trên PDF không có bảng, trả về Code: no_content thay vì tệp rỗng. Xem Mã lỗi.

Làm sao dùng endpoint MCP lưu trữ sẵn?

API nhúng sẵn một máy chủ MCP tại POST https://pdf123.xyz/mcp. Xác thực bằng cùng header X-API-KEY mà REST API dùng. Không có khóa thì endpoint trả 401. Hãy tạo khóa ở trang dành cho nhà phát triển.

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

Máy chủ lưu trữ sẵn liệt kê bảy công cụ: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload và pdf_toolbox_download. Mỗi công cụ theo danh mục nhận tên operation và tham số của nó, cùng một tệp hoặc một fileId do công cụ tải lên trả về. Hãy dùng công cụ describe để lấy schema của một thao tác.

Câu hỏi thường gặp

MCP là gì?

MCP, tức Model Context Protocol, là chuẩn mở để kết nối các ứng dụng AI với công cụ bên ngoài. Một ứng dụng như Claude Code khởi chạy hoặc kết nối tới máy chủ MCP, liệt kê các công cụ của nó và gọi chúng thay mặt người dùng.

Máy chủ MCP cục bộ có hoạt động ngoại tuyến không?

Không. Nó tải tệp lên API PDF123, hoặc máy chủ được chỉ định trong PDFX_API_BASE, rồi lưu kết quả về máy. Phải truy cập được API base.

Có cần khóa API không?

Máy chủ cục bộ không cần khóa khi dùng ẩn danh. Hãy đặt PDFX_API_KEY nếu máy chủ của bạn yêu cầu khóa. Endpoint lưu trữ sẵn tại /mcp luôn cần header X-API-KEY.

Agent có đọc được mọi tệp trên máy tính của tôi không?

Theo mặc định, nó đọc được mọi đường dẫn mà tiến trình máy chủ truy cập được. Hãy đặt PDFX_MCP_ROOT để giới hạn việc đọc và ghi trong các thư mục bạn chọn.

Tệp của tôi được xử lý ra sao?

Máy chủ cục bộ tải từng đầu vào lên API PDF123, hoặc máy chủ riêng của bạn, để xử lý. Mô tả công cụ nêu rõ rằng tệp được xóa ở đó sau khi xử lý. Kết quả được lưu trên máy của bạn. Để biết chi tiết, hãy đọc trang quyền riêng tư tệp.

Agent dùng được bao nhiêu công cụ?

Máy chủ cục bộ truy cập cả 97 công cụ trong danh mục thông qua năm công cụ MCP. Endpoint lưu trữ sẵn gom các thao tác theo danh mục (convert, pages, misc và security) sau bảy công cụ MCP.