Python में अपना पहला MCP सर्वर कैसे बनाएं (और उसे बिना AI ऐप के टेस्ट करें)

Python में दो टूल वाला एक छोटा MCP सर्वर लिखें, उसे बिना किसी AI ऐप के टेस्ट करें, MCP Inspector से जांचें और अपने एडिटर या असिस्टेंट से जोड़ें।

Graphic of a small server box connected to a chat bubble and a code editor, for a guide to building an MCP server in Python

Model Context Protocol (MCP) की ज़्यादातर गाइड आपको बस किसी और का लिखा सर्वर इंस्टॉल करना सिखाती हैं। यह गाइड आपको Python में अपना खुद का MCP सर्वर बनाना सिखाती है: दो टूल वाला एक छोटा सर्वर, जिसे MCP सपोर्ट करने वाला कोई भी AI ऐप कॉल कर सकता है। आप इसे बनाएंगे, बिना किसी AI ऐप के टेस्ट करेंगे, आधिकारिक MCP Inspector से जांचेंगे और फिर किसी एडिटर या असिस्टेंट से जोड़ेंगे।

मुख्य बातें

  • आधिकारिक MCP Python SDK 2.x में सर्वर क्लास का नाम बदलकर MCPServer कर दिया गया है, इसलिए कई पुराने ट्यूटोरियल अब वैसे नहीं चलते जैसे लिखे गए थे।
  • किसी फ़ंक्शन पर @mcp.tool() डेकोरेटर लगाते ही वह टूल बन जाता है; उसका नाम, विवरण और इनपुट स्कीमा आपके कोड से ही बनते हैं।
  • सर्वर को पहले SDK की Client क्लास से मेमोरी में टेस्ट करें, फिर आधिकारिक MCP Inspector से stdio पर।
  • ऐप को absolute path वाली uv लॉन्च कमांड देकर इसे Cursor, VS Code या Claude Desktop से जोड़ें।

15 नवंबर 2026 तक आधिकारिक Python SDK का वर्ज़न 2.3.0 है (2 अक्टूबर 2026 को रिलीज़) और MCP Inspector का वर्ज़न 2.15.0 है (12 नवंबर 2026 को रिलीज़)। SDK 2.x में मुख्य सर्वर क्लास का नाम बदल गया है, इसलिए कई पुराने ट्यूटोरियल अब वैसे नहीं चलते जैसे लिखे गए थे। नीचे दी गई प्रोजेक्ट, टेस्ट और Inspector कमांड इन्हीं वर्ज़न पर चलाकर देखी गई हैं।

MCP सर्वर क्या है

MCP AI ऐप्स को बाहरी सिस्टम से जोड़ने का एक ओपन-सोर्स स्टैंडर्ड है। साथ चलने के लिए SDK docs के ये तीन शब्द काफ़ी हैं:

  • होस्ट वह AI ऐप है जिससे आप बात करते हैं, जैसे कोई चैट असिस्टेंट या कोड एडिटर।
  • क्लाइंट होस्ट के अंदर रहता है और MCP में बात करता है।
  • सर्वर वह है जो आप बनाते हैं। यह टूल (वे फ़ंक्शन जिन्हें मॉडल कॉल करता है), रिसोर्स (वह डेटा जिसे ऐप लोड करता है) और प्रॉम्प्ट (वे टेम्पलेट जिन्हें यूज़र चुनता है) दे सकता है।

यह गाइड सिर्फ़ टूल पर रहती है। आप जो दो टूल लिखेंगे, एक शब्द गिनने वाला और एक तारीखों का हिसाब लगाने वाला, वे ऐसा सटीक काम करते हैं जो मॉडल के अंदाज़े से बेहतर कोड करता है।

वीडियो: The Model Context Protocol (MCP) (Anthropic)

आपको क्या चाहिए

  • uv, वह Python प्रोजेक्ट मैनेजर जो आधिकारिक MCP ट्यूटोरियल में इस्तेमाल होता है। सही वर्ज़न न होने पर यह Python खुद डाउनलोड कर लेता है। SDK के लिए Python 3.10 या उससे नया वर्ज़न चाहिए।
  • Node.js, सिर्फ़ स्टेप 4 के Inspector के लिए। Inspector 2.15.0 के लिए Node ^22.23.4 || ^24.22.1 || >=26.12.1 चाहिए।
  • स्टेप 5 के लिए MCP सपोर्ट करने वाला कोई ऐप (वैकल्पिक)।

macOS या Linux पर uv इंस्टॉल करें:

टर्मिनल
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows पर, PowerShell में:

कोड
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

इसके बाद अपना टर्मिनल रीस्टार्ट करें ताकि uv कमांड मिल जाए।

आंकड़ों में

2.3.0इस्तेमाल किया गया Python SDK वर्ज़न

2.15.0इस्तेमाल किया गया MCP Inspector वर्ज़न

3.10Python का न्यूनतम वर्ज़न

स्टेप 1: प्रोजेक्ट बनाएं

टर्मिनल
uv init --bare handy-tools
cd handy-tools
uv add "mcp[cli]"

--bare सिर्फ़ एक pyproject.toml बनाता है, और इस प्रोजेक्ट को बस इतना ही चाहिए। cli extra से mcp कमांड-लाइन टूल जुड़ जाता है। इंस्टॉल की पुष्टि करें:

टर्मिनल
uv run mcp version

अपेक्षित आउटपुट:

कोड
MCP version 2.3.0

स्टेप 2: सर्वर लिखें

प्रोजेक्ट फ़ोल्डर में server.py नाम की फ़ाइल बनाएं:

कोड
from datetime import date

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

mcp = MCPServer("Handy Tools")


@mcp.tool()
def count_words(text: str) -> int:
    """Count the words in a piece of text."""
    return len(text.split())


@mcp.tool()
def days_between(start: str, end: str) -> int:
    """Count the days from one date to another. Dates use YYYY-MM-DD format."""
    try:
        first = date.fromisoformat(start)
        second = date.fromisoformat(end)
    except ValueError:
        raise ToolError("Dates must look like 2026-11-15 (YYYY-MM-DD).")
    return (second - first).days


if __name__ == "__main__":
    mcp.run()

हर हिस्सा क्या करता है:

  • MCPServer("Handy Tools") सर्वर बनाता है। SDK 2.x में आप इसे mcp.server से import करते हैं।
  • @mcp.tool() किसी फ़ंक्शन को टूल बना देता है। SDK टूल का नाम फ़ंक्शन के नाम से, विवरण docstring से और इनपुट स्कीमा type hints से पढ़ता है। आपको कोई JSON नहीं लिखना पड़ता।
  • ToolError मॉडल को पढ़ने लायक मैसेज वापस भेजता है, ताकि वह अपने आर्ग्युमेंट ठीक करके दोबारा कोशिश कर सके।
  • बिना आर्ग्युमेंट के mcp.run() सर्वर को stdio पर शुरू करता है: होस्ट आपकी फ़ाइल को subprocess के रूप में चलाता है और stdin व stdout के ज़रिए उससे बात करता है।
डायग्राम जिसमें एक छोटी Python MCP सर्वर फ़ाइल के हिस्से और हर हिस्से का काम दिखाया गया है

स्टेप 3: Python से टेस्ट करें

SDK में एक Client क्लास है जो आपके सर्वर ऑब्जेक्ट से मेमोरी में ही जुड़ जाती है, न कोई subprocess, न पोर्ट, न AI। server.py के बगल में check.py बनाएं:

कोड
import asyncio

from mcp import Client

from server import mcp


async def main() -> None:
    async with Client(mcp) as client:
        tools = await client.list_tools()
        print([tool.name for tool in tools.tools])

        result = await client.call_tool("count_words", {"text": "the quick brown fox"})
        print(result.structured_content)

        result = await client.call_tool("days_between", {"start": "2026-11-15", "end": "2027-01-01"})
        print(result.structured_content)

        result = await client.call_tool("days_between", {"start": "tomorrow", "end": "2027-01-01"})
        print(result.is_error, result.content[0].text)


asyncio.run(main())

इसे चलाएं:

टर्मिनल
uv run check.py

अपेक्षित आउटपुट:

कोड
['count_words', 'days_between']
{'result': 4}
{'result': 47}
True Error executing tool days_between: Dates must look like 2026-11-15 (YYYY-MM-DD).

आपको फ़ेल हुई कॉल के बारे में एक INFO लॉग लाइन भी दिखेगी, यह सर्वर का ToolError लॉग करना है। ध्यान दें कि गलत तारीख से क्लाइंट में कोई exception नहीं आया: फ़ेल हुई टूल कॉल एक सामान्य नतीजे के रूप में लौटती है, जिसमें is_error की वैल्यू True होती है।

क्या आप जानते हैं?

फ़ेल हुई टूल कॉल से क्लाइंट में exception नहीं आता। वह एक सामान्य नतीजे के रूप में लौटती है, जिसमें is_error की वैल्यू True होती है और ToolError का मैसेज साथ होता है।

स्टेप 4: MCP Inspector से जांचें

MCP Inspector MCP प्रोजेक्ट का अपना टेस्टिंग टूल है। इसका CLI मोड आपके सर्वर को वैसे ही लॉन्च करता है जैसे कोई असली होस्ट करता, और जो वापस आता है उसे प्रिंट करता है। प्रोजेक्ट फ़ोल्डर से:

टर्मिनल
npx @modelcontextprotocol/inspector --cli uv run server.py --method tools/list

पहली बार चलाने पर यह पैकेज डाउनलोड करने की अनुमति मांगता है। इसके बाद आपको JSON दिखना चाहिए जिसमें count_words और days_between हों, दोनों के साथ वह इनपुट स्कीमा जो SDK ने आपके type hints से बनाया।

अब एक टूल कॉल करें:

टर्मिनल
npx @modelcontextprotocol/inspector --cli uv run server.py \
  --method tools/call --tool-name days_between \
  --tool-args-json '{"start":"2026-11-15","end":"2027-01-01"}'

अपेक्षित आउटपुट:

कोड
{
  "content": [
    {
      "type": "text",
      "text": "47"
    }
  ],
  "structuredContent": {
    "result": 47
  },
  "isError": false
}

SDK से Inspector का वेब इंटरफ़ेस भी शुरू किया जा सकता है:

टर्मिनल
uv run mcp dev server.py

यह http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=... जैसा एक लोकल पता प्रिंट करता है और उसे आपके ब्राउज़र में खोल देता है। Servers स्क्रीन पर अपने सर्वर के बगल वाला connect स्विच ऑन करें, Tools खोलें, count_words चुनें, कुछ टेक्स्ट लिखें और Execute Tool पर क्लिक करें। काम हो जाने पर टर्मिनल में Ctrl+C दबाएं।

स्टेप 5: इसे किसी AI ऐप से जोड़ें

होस्ट से जोड़ने का मतलब है उसे वह कमांड बताना जो आपका सर्वर शुरू करती है। इस प्रोजेक्ट के लिए वह कमांड है:

टर्मिनल
uv --directory /ABSOLUTE/PATH/TO/handy-tools run server.py

असली path पाने के लिए प्रोजेक्ट फ़ोल्डर के अंदर pwd चलाएं। पहले खुद यह कमांड चलाकर देखें। कुछ प्रिंट नहीं होता और कमांड खत्म नहीं होती, और यही सही है: सर्वर किसी होस्ट के बोलने का इंतज़ार कर रहा है। रोकने के लिए Ctrl+C दबाएं।

कई ऐप उस कमांड के लिए एक ही JSON ब्लॉक स्वीकार करते हैं:

कोड
{
  "mcpServers": {
    "handy-tools": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/handy-tools", "run", "server.py"]
    }
  }
}

यह कहां जाएगा, यह ऐप पर निर्भर है:

  • Cursor: Cursor’s MCP docs के अनुसार इसे किसी प्रोजेक्ट में .cursor/mcp.json के रूप में सेव करें, या हर जगह इस्तेमाल करने के लिए ~/.cursor/mcp.json में। उन docs में लोकल सर्वर के लिए "type": "stdio" फ़ील्ड भी बताई गई है, हालांकि उनके अपने उदाहरणों में यह नहीं है।
  • VS Code: VS Code docs के अनुसार Command Palette से MCP: Add Server चलाएं, Command (stdio) चुनें और लॉन्च कमांड डालें।
  • Claude Desktop: uv run mcp install server.py चलाएं, जो एंट्री आपके लिए खुद लिख देता है। यह इकलौता होस्ट है जिसे SDK अपने आप कॉन्फ़िगर करता है।

ऐप रीस्टार्ट करें, फिर कुछ ऐसा पूछें:

कोड
Use the days_between tool: how many days from 2026-11-15 to 2027-01-01?

जवाब 47 आना चाहिए। याद रखें कि टूल आपके कंप्यूटर पर आपके अकाउंट की अनुमतियों के साथ चलते हैं, इसलिए सिर्फ़ वही काम खोलें जिन्हें कोई मॉडल चलाए तो आपको परेशानी न हो। किसी बड़े, तैयार सर्वर का उदाहरण देखने के लिए हमारी Chrome DevTools MCP गाइड देखें।

फ़्लो डायग्राम: Python MCP सर्वर बनाना, टेस्ट करना, जांचना और किसी AI ऐप से जोड़ना

आम एरर और उनके हल

  • ModuleNotFoundError: No module named 'mcp.server.fastmcp': कोड SDK 1.x के लिए लिखा गया था। 2.x में क्लास का नाम MCPServer है, जिसे from mcp.server import MCPServer से import किया जाता है। import अपडेट करें, या पुराना कोड चलाते रहने के लिए mcp<2 पर वर्ज़न पिन करें।
  • TypeError: The @tool decorator was used incorrectly: आपने बिना कोष्ठक के @mcp.tool लिखा है। @mcp.tool() इस्तेमाल करें।
  • ऐप में आपका सर्वर नहीं दिखता: आम वजह relative path होता है। प्रोजेक्ट का absolute path इस्तेमाल करें, और अगर ऐप को uv नहीं मिलता, तो uv की जगह which uv (macOS और Linux) या where uv (Windows) से मिला पूरा path लिखें। कॉन्फ़िग बदलने के बाद ऐप को पूरी तरह बंद करके दोबारा खोलें।
  • कनेक्शन टूट जाता है या टूल लिस्ट खाली है: stdio पर stdout खुद प्रोटोकॉल ले जाता है। एक भटका हुआ print() उसे खराब कर सकता है। Python का logging मॉड्यूल इस्तेमाल करें, जो stderr पर लिखता है।
  • npm warn deprecated @modelcontextprotocol/inspector@0.15.0: v1 is deprecated, या टूल कॉल Field required के साथ फ़ेल होती है: आपका Node.js, Inspector 2.x के लिए बहुत पुराना है। Node 20 पर एक टेस्ट में npx ने चुपचाप पुराना 0.15.0 रिलीज़ इंस्टॉल कर दिया, जो --tool-args-json को नज़रअंदाज़ करता है। node --version चेक करें और सपोर्टेड रिलीज़ पर अपग्रेड करें।
  • mcp dev चलाते समय npx not found: Inspector एक Node.js ऐप है। पहले Node.js इंस्टॉल करें।
  • बिना किसी मैसेज के Error executing tool <name>: टूल किसी ऐसे exception से क्रैश हुआ जिसकी आपने तैयारी नहीं की थी। traceback सर्वर के लॉग में है, नतीजे में नहीं।

क्या आप जानते हैं?

stdio पर stdout खुद प्रोटोकॉल ले जाता है, इसलिए आपके सर्वर में एक भटका हुआ print() कनेक्शन खराब कर सकता है। Python का logging मॉड्यूल इसकी जगह stderr पर लिखता है।

निष्कर्ष

एक काम करता MCP सर्वर बस कुछ डेकोरेट किए गए फ़ंक्शन वाली एक Python फ़ाइल है। टूल लिखें, Client(mcp) से मेमोरी में जांचें, Inspector से stdio पर पुष्टि करें, फिर किसी भी होस्ट को लॉन्च कमांड दे दें। यहां से आप रिसोर्स और प्रॉम्प्ट जोड़ सकते हैं, या mcp.run(transport="streamable-http") से यही कोड HTTP पर चला सकते हैं। अगर आपके एजेंट को नए फ़ंक्शन से ज़्यादा लिखित निर्देश चाहिए, तो हमारी Claude Code में agent skills की गाइड वह पहलू समझाती है।

अक्सर पूछे जाने वाले सवाल

MCP होस्ट, क्लाइंट और सर्वर में क्या फ़र्क है?

होस्ट वह AI ऐप है जिससे आप बात करते हैं, जैसे कोई चैट असिस्टेंट या कोड एडिटर। क्लाइंट होस्ट के अंदर रहता है और MCP में बात करता है। सर्वर वह है जो आप बनाते हैं, और यह टूल, रिसोर्स और प्रॉम्प्ट दे सकता है।

मुझे No module named mcp.server.fastmcp एरर क्यों मिलता है?

वह कोड SDK 1.x के लिए लिखा गया था। 2.x में क्लास का नाम MCPServer है, जिसे from mcp.server import MCPServer से import किया जाता है। import अपडेट करें, या पुराना कोड चलाते रहने के लिए mcp<2 पर वर्ज़न पिन करें।

क्या मैं MCP सर्वर को बिना AI ऐप के टेस्ट कर सकता हूं?

हां। SDK की Client क्लास आपके सर्वर ऑब्जेक्ट से मेमोरी में जुड़ जाती है, न कोई subprocess, न पोर्ट, न AI। इसके बाद MCP Inspector का CLI मोड सर्वर को stdio पर वैसे ही लॉन्च करता है जैसे कोई असली होस्ट करता।

MCP Inspector को Node.js का कौन सा वर्ज़न चाहिए?

Inspector 2.15.0 के लिए Node ^22.23.4, ^24.22.1 या >=26.12.1 चाहिए। पुराने Node पर npx चुपचाप पुराना 0.15.0 रिलीज़ इंस्टॉल कर सकता है, जो –tool-args-json को नज़रअंदाज़ करता है।

छोटा क्विज़

SDK 2.x में कौन सी क्लास MCP सर्वर बनाती है?

  • FastMCP
  • ToolError
  • MCPServer

SDK 2.x में मुख्य सर्वर क्लास का नाम बदलकर MCPServer कर दिया गया, जो mcp.server से import होती है।

एक भटका हुआ print() stdio MCP सर्वर का क्या कर सकता है?

  • प्रोटोकॉल स्ट्रीम खराब कर सकता है
  • कुछ नहीं, आउटपुट नज़रअंदाज़ हो जाता है
  • सर्वर रीस्टार्ट कर सकता है

stdio पर stdout खुद प्रोटोकॉल ले जाता है, इसलिए फ़ालतू आउटपुट उसे खराब कर सकता है।

SDK किसी टूल का इनपुट स्कीमा कहां से लेता है?

  • आपकी लिखी एक JSON फ़ाइल से
  • फ़ंक्शन के type hints से
  • होस्ट की कॉन्फ़िग फ़ाइल से

SDK इनपुट स्कीमा type hints से पढ़ता है, इसलिए आपको कोई JSON नहीं लिखना पड़ता।

स्रोत

लिंक आखिरी बार 15 नवंबर 2026 को जांचे गए।

लेखक: Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

Mindloop Experience के बारे में

प्रतिक्रियाएँ

प्रतिक्रिया लिखें

Mindloop Experience से और

Mindloop Experience के सभी लेख

आप 50 बार तक ताली बजा सकते हैं।