Python और TypeScript में कॉपी करने लायक MCP सर्वर के उदाहरण, जो GitHub पर मौजूद आधिकारिक SDK रिपॉज़िटरी पर बने हैं। हर सैंपल stdio या Streamable HTTP पर चलता है, और आख़िरी दो इमेज और वीडियो API को रैप करते हैं, ताकि असिस्टेंट चैट विंडो से मीडिया जनरेट कर सके।
MCP सर्वर एक छोटा प्रोग्राम है जो AI असिस्टेंट को टूल्स की एक सूची देता है, जिन्हें वह कॉल कर सकता है। यह समझने का सबसे तेज़ तरीका यह है कि कुछ ऐसे सर्वर पढ़े जाएँ जो पहले से चल रहे हैं। यह लेख Python और TypeScript में MCP सर्वर के उदाहरण इकट्ठा करता है, जो GitHub पर आधिकारिक SDK रिपॉज़िटरी के हिसाब से लिखे गए हैं, ताकि आप कुछ ही मिनटों में फ़ाइल कॉपी करें, उसे शुरू करें और असिस्टेंट को उसका इस्तेमाल करते हुए देखें।
नीचे का सब कुछ अक्टूबर 2026 तक के SDK डॉक्यूमेंटेशन के अनुसार है, और यह इसलिए मायने रखता है क्योंकि दोनों SDK हाल ही में अपने दूसरे मेजर वर्ज़न पर पहुँचे हैं। Python में FastMCP बदलकर MCPServer हो गया है। TypeScript में सर्वर का कोड अपने अलग @modelcontextprotocol/server पैकेज में चला गया है। लेख का पहला हिस्सा दोनों भाषाओं में एक सादा सर्वर बनाता है। दूसरे हिस्से में ऐसे टूल्स जुड़ते हैं जो इमेज और वीडियो जनरेट करते हैं, और यहीं से MCP सिर्फ़ डेमो न रहकर असली काम बचाने लगता है।
Model Context Protocol (MCP) एक ओपन स्टैंडर्ड है, जो किसी AI क्लाइंट को, जैसे चैट ऐप, IDE या एजेंट, वह कोड कॉल करने देता है जो आपने लिखा है। क्लाइंट एक कनेक्शन खोलता है, आपके सर्वर से पूछता है कि वह क्या-क्या देता है, और हर आइटम कब इस्तेमाल करना है, यह मॉडल तय करता है। संदेश JSON-RPC के ज़रिए जाते हैं, और आपका सर्वर खुद मॉडल को कॉल नहीं करता। वह इंतज़ार करता है कि उसे पूछा जाए, फ़ंक्शन चलाता है और नतीजा लौटाता है।
हर सर्वर तीन तरह के बिल्डिंग ब्लॉक से बनता है:
add या generate_image। इनसे साइड इफ़ेक्ट हो सकते हैं, इसलिए इन्हें सावधानी से डिज़ाइन करना चाहिए।greeting://alice या कोई फ़ाइल पाथ। क्लाइंट मॉडल को संदर्भ देने के लिए इन्हें पढ़ता है।💡 टिप: पहले टूल्स बनाएँ। GitHub पर ज़्यादातर सर्वर केवल टूल्स दिखाते हैं, और मॉडल साफ़ नामों वाली एक छोटी सूची से सही टूल ज़्यादा भरोसे से चुनता है, धुंधले नामों वाली लंबी सूची से कम भरोसे से।
दोनों आधिकारिक SDK में अब एक मौजूदा लाइन और एक मेंटेनेंस लाइन है। कोड कॉपी करने से पहले सही लाइन चुनें, क्योंकि इम्पोर्ट अलग होते हैं।
| Python | TypeScript | |
|---|---|---|
| मौजूदा (v2) | pip install "mcp[cli]", क्लास MCPServer | npm install @modelcontextprotocol/server |
| मेंटेनेंस (v1.x) | pip install "mcp[cli]<2", क्लास FastMCP | npm install @modelcontextprotocol/sdk zod |
| GitHub रिपॉज़िटरी | modelcontextprotocol/python-sdk | modelcontextprotocol/typescript-sdk |
Python की v1 लाइन अब केवल सुरक्षा सुधार प्राप्त करती है, इसलिए नए प्रोजेक्ट v2 से शुरू करें, और नीचे के Python सैंपल यही करते हैं। अगर आप कोई पुराना Python सर्वर चलाते हैं, तो माइग्रेट करने में from mcp.server.fastmcp import FastMCP को from mcp.server.mcpserver import MCPServer से बदलना और कंस्ट्रक्टर कॉल का नाम बदलना होता है। डेकोरेटर वही रहते हैं।
TypeScript के लिए पूरे सैंपल v1.x पैकेज इस्तेमाल करते हैं, जिसे ज़्यादातर मौजूदा सर्वर आज इम्पोर्ट करते हैं। उसके बाद उसी सर्वर का एक छोटा v2 वर्ज़न आता है, ताकि आप ठीक-ठीक देख सकें कि क्या बदलता है।
Python में शून्य से काम करने वाले सर्वर तक का रास्ता सबसे छोटा है, क्योंकि type hints और docstrings ही टूल स्कीमा बन जाते हैं। हाथ से JSON Schema लिखने की ज़रूरत नहीं पड़ती।
uv add "mcp[cli]" से इंस्टॉल करें (या pip install "mcp[cli]"), फिर इसे server.py नाम से सेव करें:
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("Demo")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
"""Greet someone by name."""
return f"Hello, {name}!"
@mcp.prompt()
def review_code(code: str) -> str:
"""Ask for a code review that lists bugs first."""
return f"Please review this code and list bugs first:\n\n{code}"
if __name__ == "__main__":
mcp.run(transport="stdio")
add फ़ंक्शन एक ऐसा टूल बन जाता है जिसका इनपुट स्कीमा a: int, b: int से जनरेट होता है। Docstring वह विवरण बन जाता है जिसे मॉडल तब पढ़ता है जब तय करता है कि इसे कॉल करना है या नहीं। greeting एक रिसोर्स टेम्पलेट है: जो क्लाइंट greeting://Ada पढ़ता है, उसे Hello, Ada! वापस मिलता है।
uv run mcp dev server.py # opens the MCP Inspector in your browser
uv run mcp run server.py # plain stdio, for a client to launch
uv run mcp run server.py --transport streamable-http # HTTP instead
पहले Inspector इस्तेमाल करें। वह हर टूल की सूची दिखाता है, आर्गुमेंट के लिए एक फ़ॉर्म देता है, और कच्चा JSON-RPC ट्रैफ़िक दिखाता है, जो खराब स्कीमा पकड़ने का सबसे तेज़ तरीका है। एक बार काम करने लगे, तो सर्वर को किसी क्लाइंट में रजिस्टर करें। Claude Code में यह एक लाइन है:
claude mcp add demo -- uv run mcp run server.py
TypeScript में थोड़ी ज़्यादा औपचारिकता चाहिए, क्योंकि इनपुट का वर्णन type hints की जगह Zod से करना होता है। इसके बदले रनटाइम पर वैलिडेशन मिलता है और आपके हैंडलर में टाइप्ड आर्गुमेंट मिलते हैं।
npm install @modelcontextprotocol/sdk zod से पैकेज इंस्टॉल करें और package.json में "type": "module" सेट करें। सर्वर को एक फ़ंक्शन के रूप में लिखें, ताकि दोनों ट्रांसपोर्ट उसे दोबारा इस्तेमाल कर सकें। इसे src/build-server.ts नाम से सेव करें:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
export function buildServer(): McpServer {
const server = new McpServer({ name: "demo", version: "1.0.0" });
server.registerTool(
"add",
{
title: "Add numbers",
description: "Add two numbers",
inputSchema: { a: z.number(), b: z.number() },
},
async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }],
})
);
return server;
}
फिर stdio के लिए तीन लाइन का एंट्री पॉइंट, src/stdio.ts में:
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { buildServer } from "./build-server.js";
await buildServer().connect(new StdioServerTransport());
tsc से कंपाइल करें, फिर npx @modelcontextprotocol/inspector node dist/stdio.js से जाँचें। रिसोर्स और प्रॉम्प्ट registerResource और registerPrompt के ज़रिए उसी ढाँचे में आते हैं। v1.x रिपॉज़िटरी में src/examples/server/simpleStreamableHttp.ts भी है, एक फ़ीचर-रिच सैंपल जिसमें टूल्स, रिसोर्स, प्रॉम्प्ट, लॉगिंग और वैकल्पिक OAuth हैं। जब आपका सर्वर सिर्फ़ प्रयोग से आगे बढ़कर असली काम करने लगे, तो इसे एक बार ज़रूर पढ़ें।
import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";
const server = new McpServer({ name: "demo", version: "1.0.0" });
server.registerTool(
"add",
{
description: "Add two numbers",
inputSchema: z.object({ a: z.number(), b: z.number() }),
},
async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }],
})
);
await server.connect(new StdioServerTransport());
तीन चीज़ें बदलती हैं: पैकेज का नाम, /stdio सबपाथ इम्पोर्ट, और स्कीमा, जो अब zod/v4 से एक पूरा z.object(...) बनता है, सादे फ़ील्ड ऑब्जेक्ट की जगह। हैंडलर का बॉडी कोड वही रहता है। v2 पर HTTP से सर्वर चलाना @modelcontextprotocol/express जैसे छोटे एडॉप्टर पैकेज से होता है, इसलिए HTTP सर्वर पोर्ट करने से पहले उस पैकेज का README ज़रूर पढ़ें।
ट्रांसपोर्ट ही वह अकेला फ़ैसला है जो बताता है कि आप डिप्लॉय कैसे करेंगे। टूल का कोड वही रहता है।
| stdio | Streamable HTTP | |
|---|---|---|
| सर्वर कौन शुरू करता है | क्लाइंट उसे चाइल्ड प्रोसेस के रूप में लॉन्च करता है | आप उसे चलाते हैं, क्लाइंट URL से कनेक्ट होते हैं |
| किसके लिए सबसे अच्छा | लोकल टूल्स, IDE, डेस्कटॉप ऐप | साझा या रिमोट सर्वर, टीमें |
| ऑथेंटिकेशन | आपका यूज़र और एनवायरनमेंट इनहेरिट होता है | आप इसे जोड़ते हैं (टोकन या OAuth) |
| लॉगिंग | केवल stderr | सामान्य आउटपुट ठीक है |
| स्केलिंग | हर क्लाइंट के लिए एक प्रोसेस | सामान्य वेब स्केलिंग |
stdio सर्वर उस हर चीज़ के लिए सही डिफ़ॉल्ट है जो आपकी अपनी मशीन को छूती है, जैसे फ़ाइलें, लोकल डेटाबेस या कोई स्क्रिप्ट। क्लाइंट उसे स्पॉन करता है, उसके stdin और stdout से बात करता है, और सेशन खत्म होने पर उसे बंद कर देता है। यहाँ कोई पोर्ट सुरक्षित करने की ज़रूरत नहीं होती।
Streamable HTTP से एक चलता हुआ सर्वर कई क्लाइंट्स को जवाब दे सकता है। यह स्टेटलेस Express वर्ज़न हर रिक्वेस्ट के लिए एक नया सर्वर बनाता है, जिससे साझा सेशन स्टेट से बचा जाता है। इसे src/http.ts नाम से सेव करें:
import express from "express";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { buildServer } from "./build-server.js";
const app = express();
app.use(express.json());
app.post("/mcp", async (req, res) => {
const server = buildServer();
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
});
res.on("close", () => {
transport.close();
server.close();
});
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
});
app.listen(3000, "127.0.0.1");
इसे claude mcp add --transport http demo http://127.0.0.1:3000/mcp के साथ रजिस्टर करें। Python में इसके बराबर एक लाइन है: mcp.run(transport="streamable-http", host="127.0.0.1", port=9000)। सर्वर को localhost पर ही बाँधें, जब तक सर्वर के सामने कोई ऐसी चीज़ न हो जो ऑथेंटिकेशन सँभालती हो, क्योंकि खुला MCP पोर्ट उन सभी टूल्स का खुला दरवाज़ा है जो आपने रजिस्टर किए हैं।
टूल तब ज़्यादा दिलचस्प होते हैं जब नतीजा कोई संख्या न हो। इमेज और वीडियो जनरेशन अच्छे सिखाने वाले उदाहरण हैं, क्योंकि ये धीमे होते हैं, असिंक्रोनस होते हैं, और टेक्स्ट की जगह URL लौटाते हैं। नीचे के सैंपल PicassoIA API को कॉल करते हैं, जो Replicate जैसी शैली में चलता है: प्रिडिक्शन बनाएँ, उसे पोल करें, आउटपुट पढ़ें।
https://api.picassoia.com/v1 के साथ हेडर Authorization: Bearer pia_sk_...POST /models/{owner}/{name}/predictions बॉडी {"input": {...}} के साथGET /predictions/{id} तब तक जब तक स्टेटस succeeded, failed या canceled न होeta.next_poll_in_seconds आता है, एक पोलिंग इंटरवल जिसका सम्मान करना चाहिएimport asyncio
import os
import httpx
from mcp.server.mcpserver import MCPServer
API = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_API_TOKEN']}"}
mcp = MCPServer("picassoia-media")
slots = asyncio.Semaphore(5) # the account allows 5 concurrent predictions
async def run_prediction(model: str, payload: dict, timeout_s: int = 600) -> list[str]:
async with slots, httpx.AsyncClient(headers=HEADERS, timeout=30) as http:
created = await http.post(
f"{API}/models/{model}/predictions", json={"input": payload}
)
created.raise_for_status()
prediction = created.json()
waited = 0
while prediction["status"] in ("starting", "processing"):
if waited >= timeout_s:
raise TimeoutError(f"Prediction {prediction['id']} is still running")
delay = (prediction.get("eta") or {}).get("next_poll_in_seconds", 3)
await asyncio.sleep(delay)
waited += delay
polled = await http.get(f"{API}/predictions/{prediction['id']}")
polled.raise_for_status()
prediction = polled.json()
if prediction["status"] != "succeeded":
raise RuntimeError(f"Prediction {prediction['status']}: {prediction.get('error')}")
output = prediction["output"]
return output if isinstance(output, list) else [output]
@mcp.tool()
async def generate_image(prompt: str, aspect_ratio: str = "16:9") -> str:
"""Generate one image from a text prompt and return its URL."""
urls = await run_prediction(
"picassoia/picassoia-image",
{"prompt": prompt, "aspect_ratio": aspect_ratio, "num_outputs": 1},
)
return urls[0]
if __name__ == "__main__":
mcp.run(transport="stdio")
यहाँ दो बातें मायने रखती हैं। लूप asyncio.sleep इस्तेमाल करता है, ताकि जॉब चलने के दौरान भी सर्वर दूसरी रिक्वेस्ट्स का जवाब दे सके, और वह API के सुझाए इंटरवल का पालन करता है, न कि उस पर बार-बार अनुरोध बरसाता है। सेमाफ़ोर आपको अकाउंट की कंकरेंसी लिमिट के भीतर रखता है। PicassoIA Image मॉडल prompt, aspect_ratio, seed, num_outputs (1 या 2), output_format और output_quality स्वीकार करता है। एडिट के लिए, उसी हेल्पर को PicassoIA Image Editor Pro की ओर इंगित करें।
वही पैटर्न TypeScript में भी काम करता है। यह वर्ज़न पहले वाले buildServer फ़ंक्शन के ऊपर एक वीडियो टूल जोड़ता है:
const API = "https://api.picassoia.com/v1";
const headers = {
Authorization: `Bearer ${process.env.PICASSOIA_API_TOKEN}`,
"Content-Type": "application/json",
};
async function runPrediction(model: string, input: Record<string, unknown>) {
const created = await fetch(`${API}/models/${model}/predictions`, {
method: "POST",
headers,
body: JSON.stringify({ input }),
});
if (!created.ok) throw new Error(`Create failed: ${created.status}`);
let prediction = await created.json();
while (["starting", "processing"].includes(prediction.status)) {
const delay = prediction.eta?.next_poll_in_seconds ?? 5;
await new Promise((resolve) => setTimeout(resolve, delay * 1000));
const polled = await fetch(`${API}/predictions/${prediction.id}`, { headers });
prediction = await polled.json();
}
if (prediction.status !== "succeeded") {
throw new Error(`Prediction ${prediction.status}`);
}
return [prediction.output].flat() as string[];
}
server.registerTool(
"generate_video",
{
title: "Generate video",
description: "Make a short clip with synchronized audio from a text prompt",
inputSchema: {
prompt: z.string().max(4000),
duration: z.union([z.literal(5), z.literal(10)]).default(5),
resolution: z.enum(["480p", "720p"]).default("720p"),
},
},
async ({ prompt, duration, resolution }) => {
const [url] = await runPrediction("picassoia/seedance-2.5-lite", {
prompt,
duration,
resolution,
});
return { content: [{ type: "text", text: url }] };
}
);
वीडियो धीमा होता है। Seedance 2.5 Lite मॉडल के पेज पर लगभग 100 से 190 सेकंड के उदाहरण रन दिखाए गए हैं, जो इतना लंबा है कि कुछ क्लाइंट एक ही टूल कॉल पर हार मान लेते हैं। एक सुरक्षित डिज़ाइन काम को दो हिस्सों में बाँटता है: start_video तुरंत प्रिडिक्शन id लौटाता है, और check_video वह id लेकर या तो स्टेटस या अंतिम URL लौटाता है।
claude.ai के लिए PicassoIA कनेक्टर ठीक ऐसे ही काम करता है। उसके जनरेट टूल predict_id और एक सुझाया गया इंतज़ार समय लौटाते हैं, और get_generation तब तक कॉल होता है जब तक जॉब सफल या विफल नहीं हो जाता। यही मॉडल एक वैकल्पिक image पहले फ़्रेम के रूप में, एक seed, एक aspect_ratio और साइलेंट क्लिप्स के लिए save_audio फ़्लैग भी लेता है।
💡 टिप: टूल का नतीजा छोटा रखें। फ़ाइल की जगह URL और एक लाइन का सार लौटाएँ। असिस्टेंट को दिखाने या आगे भेजने के लिए बस एक लिंक चाहिए।
असिस्टेंट से PicassoIA तक पहुँचने के दो तरीके हैं: तैयार कनेक्टर, या ऊपर के सैंपल की तरह API के चारों ओर अपना सर्वर।
generate_image, edit_image, generate_video_picassoia, generate_video_seedance, get_generation, cancel_generation, list_models, get_account और list_generations देता है। अपने खुद के एजेंट कोड के लिए API रास्ता इस्तेमाल करें।pia_sk_ से शुरू होता है, और एक अकाउंट में अधिकतम दो टोकन रह सकते हैं। किसी भी चीज़ पर निर्माण करने से पहले देखें कि कौन-सा प्लान API एक्सेस शामिल करता है, इसके लिए प्राइसिंग पेज जाँचें।export PICASSOIA_API_TOKEN=pia_sk_... चलाएँ। इसे सोर्स फ़ाइलों से बाहर रखें, और किसी भी क्लाइंट कॉन्फ़िग से बाहर रखें जिसे आप कमिट करते हैं।| मॉडल | इसका उपयोग |
|---|---|
| PicassoIA Image | टेक्स्ट से इमेज, हर कॉल में एक या दो आउटपुट |
| PicassoIA Image Editor Pro | इमेज एडिट करना और मिलाना |
| PicassoIA Video | टेक्स्ट या इमेज से वीडियो |
| Seedance 2.5 Lite | सिंक्रोनाइज़्ड ऑडियो के साथ टेक्स्ट या इमेज से वीडियो, 5 या 10 सेकंड |
आपके टूल्स कब कॉल करने हैं, यह कौन-सा मॉडल तय करता है? कोई भी टूल-कॉलिंग LLM कर सकता है। PicassoIA का लार्ज लैंग्वेज मॉडल कैटलॉग Claude Sonnet 5, GPT 5.6 Sol, Kimi K2.6 और Gemini 3.5 Flash, तथा कई अन्य सूचीबद्ध करता है। एक ही सर्वर पर एक से ज़्यादा आज़माएँ और देखें कि हर एक सही टूल कितनी भरोसेमंदी से चुनता है।
ज़्यादातर असफल पहली कोशिशें तीन में से किसी एक समस्या तक जाती हैं। हर एक से बचना आसान है, बस यह पता हो कि कहाँ देखना है।
stdio में, standard output ही प्रोटोकॉल चैनल है। कोई भटका हुआ print() या console.log() JSON-RPC स्ट्रीम को खराब कर देता है, और क्लाइंट parse error या ऐसा सर्वर बताता है जो कभी कनेक्ट ही नहीं हुआ। इसके बजाय लॉग को standard error पर भेजें:
import sys
print("polling prediction", file=sys.stderr) # safe
# print("polling prediction") # breaks stdio
TypeScript में console.error("polling prediction") इस्तेमाल करें।
एसिंक टूल के अंदर time.sleep(30) उसी सर्वर पर बाकी हर रिक्वेस्ट को जाम कर देता है। Python में await asyncio.sleep इस्तेमाल करें और TypeScript में awaited timer, जैसा सैंपल करते हैं। नाम भी उतने ही मायने रखते हैं: do_task नाम वाले टूल के पास मॉडल के चुनने के लिए कुछ नहीं होता, जबकि generate_image नाम और साफ़ docstring मॉडल को ठीक बताता है कि टूल कब उठाना है।
टोकन एनवायरनमेंट वेरिएबल से पढ़ें, सोर्स फ़ाइलों से कभी नहीं, और उन्हें कभी टूल के नतीजे में इको न करें। आउटपुट के लिए base64 की जगह URL लौटाएँ। एक अकेली base64 इमेज कई मेगाबाइट तक जा सकती है और मॉडल की कॉन्टेक्स्ट विंडो भर देती है, और PicassoIA API वैसे भी रिक्वेस्ट बॉडी को 10 MB पर सीमित करता है।
server.py या TypeScript की जोड़ी कॉपी करें, Inspector में चलाएँ, और दस मिनट से कम में आपके पास एक काम करता MCP सर्वर होगा। फिर उसे कुछ विज़ुअल करने को दें। GitHub पर आधिकारिक रेफ़रेंस सर्वर और अधिक पैटर्न पढ़ने की अच्छी जगह हैं, और दोनों SDK रिपॉज़िटरी में एक examples फ़ोल्डर है।
PicassoIA Image खोलें और अपना खुद का प्रॉम्प्ट लिखें, Image Editor Pro से कोई शॉट एडिट करें, या Seedance 2.5 Lite से एक फ़्रेम को एनिमेट करें। आप जो भी बनाएँ, लूप वही रहता है: वर्णन करें, सबमिट करें, पोल करें, समीक्षा करें।
Picasso IA से अपनी खुद की इमेज बनाकर देखें, और जब कोई प्रॉम्प्ट काम कर जाए, तो उसे एक टूल के रूप में रैप करें, ताकि आपका असिस्टेंट उसे जब चाहे दोहरा सके।
अपनी भाषा चुनें
