मुख्य सामग्री पर जाएँ
PPDF123

AI एजेंट के लिए PDF123 MCP सर्वर

MCP यानी Model Context Protocol एक खुला मानक है, जिससे Claude Code, Claude Desktop और Cursor जैसे AI क्लाइंट बाहरी टूल कॉल कर सकते हैं। 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स्थानीय फ़ाइलों पर एक टूल चलाता है और सेव किया गया पथ या JSON रिपोर्ट लौटाता हैtool, 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 पर pdf-to-csv, वह खाली फ़ाइल के बजाय Code: no_content लौटाता है। देखें त्रुटि कोड।

होस्टेड MCP एंडपॉइंट कैसे इस्तेमाल करें?

API में POST https://pdf123.xyz/mcp पर एक 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 टूल इस्तेमाल करें।

FAQ

MCP क्या है?

MCP यानी Model Context Protocol, AI क्लाइंट को बाहरी टूल से जोड़ने का खुला मानक है। Claude Code जैसा क्लाइंट MCP सर्वर को शुरू करता है या उससे संपर्क करता है, उसके टूल की सूची लेता है और उपयोगकर्ता की ओर से उन्हें कॉल करता है।

क्या स्थानीय MCP सर्वर ऑफ़लाइन चलता है?

नहीं। यह फ़ाइलें PDF123 API पर, या PDFX_API_BASE में बताए सर्वर पर, अपलोड करता है और नतीजा स्थानीय रूप से सेव करता है। API बेस तक पहुँच होनी चाहिए।

क्या इसके लिए API कुंजी चाहिए?

स्थानीय सर्वर को गुमनाम उपयोग के लिए कुंजी नहीं चाहिए। यदि आपके सर्वर को कुंजी चाहिए तो PDFX_API_KEY सेट करें। /mcp पर होस्टेड एंडपॉइंट को हमेशा X-API-KEY हेडर चाहिए।

क्या एजेंट मेरे कंप्यूटर की कोई भी फ़ाइल पढ़ सकता है?

डिफ़ॉल्ट रूप से वह हर उस पथ को पढ़ सकता है जिस तक सर्वर प्रोसेस पहुँच सकता है। पढ़ना और लिखना आपकी चुनी डायरेक्टरी तक सीमित करने के लिए PDFX_MCP_ROOT सेट करें।

मेरी फ़ाइलों का क्या होता है?

स्थानीय सर्वर हर इनपुट को प्रोसेसिंग के लिए PDF123 API या आपके अपने सर्वर पर अपलोड करता है। टूल के विवरण में लिखा है कि प्रोसेसिंग के बाद फ़ाइलें वहाँ से मिटा दी जाती हैं। नतीजा आपकी मशीन पर सेव होता है। ब्योरे के लिए फ़ाइल गोपनीयता पेज पढ़ें।

एजेंट कितने टूल इस्तेमाल कर सकता है?

स्थानीय सर्वर पाँच MCP टूल के ज़रिए कैटलॉग के सभी 97 टूल तक पहुँचता है। होस्टेड एंडपॉइंट अपने ऑपरेशन श्रेणी (convert, pages, misc और security) के अनुसार सात MCP टूल के पीछे समूहित करता है।