Ollama MCP Server: लोकल मॉडल को ब्रिज से कैसे जोड़ें

आपके लैपटॉप पर पहले से ही एक सक्षम लैंग्वेज मॉडल चल सकता है, लेकिन आपके ज़्यादातर tools को उसके होने का पता ही नहीं है। Ollama MCP server सेटअप यही समस्या हल करता है। Ollama, जो मॉडल्स को localhost:11434 पर सर्व करता है, और Model Context Protocol (MCP), वह स्टैंडर्ड जिससे AI ऐप्स tools खोजते और कॉल करते हैं, इन दोनों के बीच एक छोटा bridge बैठता है। इसे एक बार बना लें, और लोकल मॉडल आपकी फ़ाइलें पढ़ सकता है, डेटाबेस से पूछताछ कर सकता है, या आपके नोट्स खोज सकता है। दिशा उलट दें, तो Claude Desktop या Claude Code अपने सस्ते, निजी काम उस GPU को सौंप सकते हैं जो आपकी मेज़ के नीचे रखा है।

यह लेख Python कोड के साथ दोनों दिशाएँ बनाता है: एक bridge client, जो Ollama मॉडल्स को किसी भी MCP server का इस्तेमाल करने देता है, और एक bridge server, जो Ollama को टूल्स के सेट के रूप में किसी भी MCP client के सामने रखता है। साथ में आपको मेमोरी के आँकड़े, कॉन्फ़िग फ़ाइलें और वे तीन बग भी मिलते हैं जो डीबगिंग का ज़्यादातर समय खा जाते हैं।

Ollama MCP Bridge क्या करता है

Ollama और MCP एक ही समस्या के अलग-अलग हिस्से हल करते हैं। Ollama ओपन वेट्स वाले मॉडल डाउनलोड करता है और उन्हें एक सादे HTTP API के ज़रिए सर्व करता है। MCP, जिसे Anthropic ने 2024 के अंत में जारी किया था, मानकीकृत करता है कि कोई AI application servers कहलाने वाले छोटे प्रोग्रामों के ज़रिए tools, फ़ाइलों और डेटा से कैसे बात करता है। Ollama का API chat messages और tool definitions की भाषा बोलता है। वह MCP की भाषा नहीं बोलता, और MCP clients को पता ही नहीं होता कि आपके मॉडल कहाँ रहते हैं। bridge इन दोनों के बीच अनुवाद करता है।

Bridge बनाने के दो तरीके

"Bridge" का मतलब इस पर निर्भर करता है कि किसे क्या चाहिए, और इसके हिसाब से दो अलग programs हो सकते हैं, इसलिए कोड लिखने से पहले दिशा तय कर लें।

पहली दिशा लोकल मॉडल को हाथ देती है। दूसरी क्लाउड assistant को एक लोकल सहकर्मी देती है। ज़्यादातर लोग दोनों बनाते हैं, क्योंकि दूसरी वाली में लगभग 30 लाइनें लगती हैं।

Transport के बारे में एक छोटी बात। यहाँ के उदाहरण stdio इस्तेमाल करते हैं, जिसमें client server को child process के रूप में शुरू करता है और standard input और output के ज़रिए उससे बात करता है। निजी मशीन के लिए यह सबसे सरल विकल्प है। अगर आप एक ही bridge को कई ऐप्स या अपने नेटवर्क की कई मशीनों के साथ साझा करना चाहते हैं, तो उसे Streamable HTTP transport पर चलाएँ और अपने firewall के पीछे रखें। Tool का कोड वही रहता है, बस server की आख़िरी लाइन बदलती है।

Tool call का सफ़र

दिशा कोई भी चुनें, tool call एक ही loop का पालन करता है:

1. Bridge एक MCP server से जुड़ता है और tools/list के साथ उसकी tool list माँगता है।
2. वह हर tool schema को उस format में बदलता है जो Ollama अपेक्षित करता है।
3. वह उपयोगकर्ता का सवाल और वे tool definitions एक लोकल मॉडल को भेजता है।
4. मॉडल टेक्स्ट की जगह एक tool_calls entry के साथ जवाब देता है।
5. Bridge उस call को tools/call के साथ MCP server पर चलाता है।
6. नतीजा एक tool message के रूप में मॉडल को वापस जाता है।
7. चरण 3 से 6 तब तक दोहराए जाते हैं जब तक मॉडल सादा टेक्स्ट में जवाब नहीं देता।

💡 मॉडल कभी आपकी डिस्क को नहीं छूता। वह सिर्फ़ एक कार्रवाई का अनुरोध करता है। कार्रवाई चलनी है या नहीं, यह आपका bridge तय करता है, और इसी वजह से allow lists, confirmation prompts और logging के लिए bridge सही जगह है।

पहले क्या चाहिए

काम करने वाला हार्डवेयर

मॉडल के वेट्स GPU मेमोरी (या Mac पर यूनिफ़ाइड मेमोरी) में फ़िट होने चाहिए, और कॉन्टेक्स्ट के लिए जगह भी बची रहनी चाहिए। ये आँकड़े अनुमानित हैं और 4-बिट क्वांटाइज़्ड बिल्ड्स के लिए हैं:

जो मॉडल system RAM में फैल जाते हैं वे अब भी चलते हैं, लेकिन token speed बहुत गिर जाती है। एक bridge हर सवाल पर कई model calls करता है, इसलिए speed साइज़ से ज़्यादा मायने रखती है। पूरी तरह GPU में फ़िट होने वाला 8B मॉडल अक्सर उस 32B मॉडल से बेहतर होता है जो फ़िट नहीं होता।

Tool calls सपोर्ट करने वाले मॉडल

हर मॉडल टूल की माँग नहीं कर सकता। Ollama मॉडल का चैट टेम्पलेट जाँचता है, और टूल सपोर्ट के बिना कोई मॉडल tools देने पर एरर लौटाता है। Ollama लाइब्रेरी को tools टैग से फ़िल्टर करें, या इस छोटी सूची से शुरू करें:

सब कुछ इंस्टॉल करें

पहले एक वर्चुअल एनवायरनमेंट सक्रिय करें (macOS और Linux पर source .venv/bin/activate, Windows पर .venv\Scripts\activate), फिर चलाएँ:

# 1. Pull a tool-capable model and confirm Ollama is serving
ollama pull llama3.1:8b
curl http://localhost:11434/api/tags

# 2. Install the two Python packages the bridge needs
pip install ollama mcp

# 3. Check Node, because the example MCP server runs through npx
node --version

प्रॉम्प्ट कॉपी करें

अगर curl आपके मॉडल्स की JSON list लौटाए, तो Ollama तैयार है। अगर connection refused मिले, तो उसे ollama serve से शुरू करें।

Python में Bridge Client बनाएँ

क्लाइंट एक ही फ़ाइल है। यह stdio transport के ज़रिए एक MCP server को चाइल्ड प्रोसेस के रूप में चालू करता है, उसके टूल्स पढ़ता है, और पिछले सेक्शन वाला लूप चलाता है। उदाहरण में इस्तेमाल हुआ server आधिकारिक फ़ाइलसिस्टम server है, जो एक नोट्स फ़ोल्डर की ओर इशारा करता है।

MCP tools को Ollama format में बदलें

हर MCP टूल के पास एक name, एक description और JSON Schema में लिखा एक inputSchema होता है। Ollama का फ़ंक्शन-कॉलिंग फ़ॉर्मैट यही तीनों चीज़ें चाहता है, जो एक function ऑब्जेक्ट में लिपटी हों। यह बदलाव ज़्यादातर नाम बदलने जैसा है:

def to_ollama_tool(tool):
    return {
        "type": "function",
        "function": {
            "name": tool.name,
            "description": tool.description or "",
            "parameters": tool.inputSchema,
        },
    }

प्रॉम्प्ट कॉपी करें

ज़्यादातर schemas बिना छुए निकल जाते हैं। अगर कोई server anyOf या $ref जैसे अनोखे constructs भेजता है, तो भेजने से पहले उन्हें flat कर लें। छोटे मॉडल flat schemas को कहीं बेहतर संभालते हैं।

Tool call loop लिखें

import asyncio

import ollama
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

MODEL = "llama3.1:8b"
NOTES_DIR = "/home/me/notes"
MAX_TURNS = 8

server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", NOTES_DIR],
)


def to_ollama_tool(tool):
    return {
        "type": "function",
        "function": {
            "name": tool.name,
            "description": tool.description or "",
            "parameters": tool.inputSchema,
        },
    }


async def ask(question: str) -> str:
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            listed = await session.list_tools()
            tools = [to_ollama_tool(t) for t in listed.tools]

            client = ollama.AsyncClient()
            messages = [{"role": "user", "content": question}]

            for _ in range(MAX_TURNS):
                response = await client.chat(model=MODEL, messages=messages, tools=tools)
                message = response.message
                messages.append(message)

                if not message.tool_calls:
                    return message.content

                for call in message.tool_calls:
                    result = await session.call_tool(
                        call.function.name, dict(call.function.arguments)
                    )
                    text = "\n".join(
                        block.text for block in result.content if block.type == "text"
                    )
                    messages.append(
                        {"role": "tool", "tool_name": call.function.name, "content": text}
                    )

            return "Stopped: the model kept calling tools."


if __name__ == "__main__":
    print(asyncio.run(ask("Which markdown files in my notes folder mention invoices?")))

प्रॉम्प्ट कॉपी करें

चार बातों पर ध्यान देना ज़रूरी है:

• MAX_TURNS एक सुरक्षा रेलिंग है। उलझा हुआ मॉडल एक ही टूल को हमेशा कॉल करता रह सकता है, और काउंटर इसे साफ़ विफलता में बदल देता है।
• dict(call.function.arguments) इसलिए ज़रूरी है कि Ollama आर्गुमेंट्स को मैपिंग के रूप में लौटाता है, जबकि MCP सेशन उन्हें सादे डिक्शनरी के रूप में चाहता है।
• सिर्फ़ टेक्स्ट ब्लॉक। MCP के नतीजों में इमेज और एम्बेडेड रिसोर्स भी हो सकते हैं। यह वर्ज़न टेक्स्ट रखता है और बाक़ी को नज़रअंदाज़ करता है।
• tool_name टूल मैसेज पर मॉडल को बताता है कि नतीजा किस कॉल का है, जिससे पैरेलल कॉल आपस में गड्डमड्ड नहीं होतीं।

असली फ़ाइलों पर इसे चलाएँ

फ़ाइल को bridge_client.py नाम से सेव करें, NOTES_DIR को किसी असली फ़ोल्डर में बदलें, और python bridge_client.py चलाएँ। एक सही run पहले डायरेक्टरी लिस्टिंग या search call करता है, फिर एक-दो फ़ाइलें पढ़ता है, और फिर सादे टेक्स्ट में जवाब देता है। मॉडल को tools चुनते हुए देखने के लिए, inner loop के सबसे ऊपर print(call.function.name, call.function.arguments) जोड़ें।

💡 Windows टिप: अगर Python npx लॉन्च नहीं कर पाता, तो command के रूप में npx.cmd इस्तेमाल करें। -y flag npx को पहली बार चलने पर बिना पूछे filesystem server इंस्टॉल करने देता है।

Bridge को किसी संवेदनशील चीज़ की ओर इशारा करने से पहले तय करें कि मॉडल क्या कर सकता है। Filesystem server सिर्फ़ उन folders तक पहुँचता है जो आप उसकी command line पर देते हैं, इसलिए अपनी home directory के बजाय एक notes folder दें। जो tools लिखते, मिटाते या डेटा भेजते हैं, उनके लिए loop के अंदर एक confirmation step जोड़ें: call प्रिंट करें और session.call_tool चलने से पहले हाँ माँगें। तीस सेकंड की रुकावट उस 8B मॉडल से बेहतर है जो कोई cleanup अच्छा विचार मान ले।

Ollama को MCP Server के रूप में उपलब्ध कराएँ

अब दिशा उलटें। लोकल मॉडल दूसरों के tools इस्तेमाल करने के बजाय, आप लोकल मॉडल को ही एक tool के रूप में प्रकाशित करते हैं। फिर कोई भी MCP client उसे ऐसे टेक्स्ट के drafting, summarizing या classification के लिए कॉल कर सकता है जो आपकी मशीन से कभी बाहर नहीं जाना चाहिए।

Python में एक छोटा server

आधिकारिक Python SDK में FastMCP शामिल है, जो आपके टाइप हिंट्स से टूल स्कीमा और आपके डॉकस्ट्रिंग से विवरण बनाता है:

import sys

import ollama
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("ollama-bridge")
client = ollama.AsyncClient()
DEFAULT_MODEL = "llama3.1:8b"


@mcp.tool()
async def list_local_models() -> list[str]:
    """List the models installed in the local Ollama instance."""
    listed = await client.list()
    return [m.model for m in listed.models]


@mcp.tool()
async def ask_local_model(
    prompt: str, model: str = DEFAULT_MODEL, temperature: float = 0.2
) -> str:
    """Send a prompt to a local Ollama model and return its reply.
    Use it for private text or cheap drafts that should stay on this machine."""
    print(f"ask_local_model: {model}", file=sys.stderr)
    response = await client.chat(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        options={"temperature": temperature},
    )
    return response.message.content


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

प्रॉम्प्ट कॉपी करें

Docstring caller के लिए लिखें, अपने लिए नहीं। Client मॉडल उसे पढ़कर तय करता है कि आपका tool कब कॉल करने लायक है, इसलिए "निजी टेक्स्ट के लिए इसका उपयोग करें" जैसी पंक्ति असली काम करती है।

Claude Desktop से जोड़ें

claude_desktop_config.json खोलें। Windows पर यह %APPDATA%\Claude में रहती है, और macOS पर ~/Library/Application Support/Claude में। mcpServers के अंतर्गत server जोड़ें:

{
  "mcpServers": {
    "ollama-bridge": {
      "command": "C:\\tools\\ollama-bridge\\.venv\\Scripts\\python.exe",
      "args": ["C:\\tools\\ollama-bridge\\ollama_bridge.py"],
      "env": { "OLLAMA_HOST": "http://127.0.0.1:11434" }
    }
  }
}

प्रॉम्प्ट कॉपी करें

command को वर्चुअल एनवायरनमेंट के Python की ओर इंगित करें, सिस्टम वाले की ओर नहीं। Claude Desktop आपका एनवायरनमेंट एक्टिवेट नहीं करता, और जिस सिस्टम इंटरप्रेटर में mcp पैकेज नहीं है, वह बिना कोई संकेत दिए फ़ेल हो जाता है। ऐप को बंद करके दोबारा खोलें, और दोनों टूल्स टूल्स मेनू में दिखने लगेंगे।

Claude Code से जोड़ें

Claude Code terminal से servers रजिस्टर करता है:

claude mcp add ollama-bridge -- /path/to/.venv/bin/python /path/to/ollama_bridge.py
claude mcp list

प्रॉम्प्ट कॉपी करें

डबल डैश के बाद की हर चीज़ लॉन्च कमांड है। जब claude mcp list में server कनेक्टेड दिखे, तो Claude Code से कहें "इस लॉग का सारांश लोकल मॉडल से बनाएँ" और देखें कि वह ask_local_model को कॉल करता है।

वे समस्याएँ ठीक करें जो आपके सामने आएँगी

तीन समस्याएँ ज़्यादातर असफल पहली कोशिशों की जड़ होती हैं। तीनों के छोटे समाधान हैं।

Stdout stdio servers को तोड़ता है

एक stdio MCP server stdout के ज़रिए JSON-RPC messages भेजता है। एक गलत print() उस stream में टेक्स्ट डाल देता है, और क्लाइंट कनेक्शन तोड़ देता है या parse error दिखाता है। इसका लक्षण यह होता है कि server कनेक्ट होता है, फिर एक सेकंड के भीतर डिसकनेक्ट हो जाता है।

इसका समाधान एक आदत है: लॉग stderr (print(..., file=sys.stderr)) या किसी फ़ाइल में लिखें, और stdout पर कभी कुछ और न लिखें। इसमें प्रोग्रेस बार और इम्पोर्ट की गई लाइब्रेरी द्वारा प्रिंट की गई चेतावनियाँ भी शामिल हैं।

छोटे मॉडल tools को नज़रअंदाज़ करते हैं

25 tools दिए जाने पर एक 8B मॉडल अक्सर याद से जवाब देता है या गलत tool चुनता है। चार बदलाव मदद करते हैं, लगभग असर के क्रम में:

• कम tools भेजें। सूची को उन तीन से छह tools तक फ़िल्टर करें जो सवाल में फ़िट बैठते हैं।
• Descriptions दोबारा लिखें। "Absolute path से एक फ़ाइल की सामग्री पढ़ें" लिखना "File reader" से बेहतर काम करता है।
• Temperature घटाएँ tool चुनने के लिए 0.1 या 0.2 तक।
• एक साइज़ ऊपर जाएँ। 3B से 8B पर जाना tool-calling की विफलताएँ किसी भी प्रॉम्प्ट ट्रिक से ज़्यादा ठीक करता है।

Context windows जल्दी भरते हैं

Tool definitions और tool results, दोनों कॉन्टेक्स्ट लेते हैं, और एक बड़ी फ़ाइल पढ़ना अकेले ही सवाल को विंडो से बाहर धकेल सकता है। Ollama का डिफ़ॉल्ट कॉन्टेक्स्ट छोटा है, इसलिए उसे साफ़-साफ़ बढ़ाएँ और नतीजों को मॉडल तक पहुँचने से पहले छाँट लें:

response = await client.chat(
    model=MODEL,
    messages=messages,
    tools=tools,
    options={"num_ctx": 8192},
)

text = text[:4000]  # trim large tool results before appending them

प्रॉम्प्ट कॉपी करें

num_ctx के ऊँचे मान attention cache के लिए ज़्यादा memory लेते हैं, इसलिए उन्हें चरणों में बढ़ाएँ। साथ ही OLLAMA_KEEP_ALIVE को 30m जैसे लंबे मान पर सेट करें। Ollama डिफ़ॉल्ट रूप से पाँच मिनट बाद निष्क्रिय मॉडल्स को unload कर देता है, और हर reload पहले जवाब में कुछ सेकंड जोड़ता है।

लोकल मॉडल या होस्टेड मॉडल

Bridge आपको कोई एक चुनने के लिए मजबूर नहीं करता। वह हर काम को उस सबसे सस्ती जगह तक भेजने देता है जो उसे अच्छी तरह कर सकती है।

लोकल मॉडल तब जीतते हैं जब:

• टेक्स्ट निजी हो, जैसे contracts, स्वास्थ्य से जुड़े नोट्स, या NDA वाला source code
• काम हज़ारों बार दोहराया जाए, इसलिए per-token pricing जुड़ती चली जाए
• आप offline काम करते हों या ऐसे नेटवर्क पर हों जिस पर आपका नियंत्रण नहीं है

होस्टेड मॉडल तब जीतते हैं जब:

• आपके GPU में 8 GB से कम मेमोरी है
• काम के लिए 30B पैरामीटर से बड़ा मॉडल चाहिए
• कोल्ड स्टार्ट पर आपको कुछ सेकंड में जवाब चाहिए

व्यवहार में hybrid सबसे अच्छा काम करता है। पहले ड्राफ़्ट, classification और निजी files को छूने वाले हर काम को लोकल मॉडल संभालने दें, फिर कठिन 10 प्रतिशत को किसी बड़े होस्टेड मॉडल पर भेजें। चूँकि दोनों एक ही MCP interface के पीछे बैठते हैं, आपका assistant ask_local_model और किसी होस्टेड विकल्प के बीच चुनाव केवल एक साफ़ tool description से कर सकता है।

PicassoIA पर होस्टेड विकल्प उपयोगी पैमाने बनते हैं। वही prompt एक लोकल 8B मॉडल और इनमें से किसी एक पर चलाएँ, और देखें कि अतिरिक्त साइज़ से असल में क्या मिलता है:

PicassoIA पर GPT OSS 20B इस्तेमाल करें

अगर आप 14 GB डाउनलोड करने से पहले gpt-oss:20b टेस्ट करना चाहते हैं, तो वही open-weight मॉडल ब्राउज़र में चलाएँ:

1. Large Language Models collection में GPT OSS 20B page खोलें।
2. Prompt फ़ील्ड में अपना prompt लिखें। एक अच्छा टेस्ट वह docstring है जो आप ask_local_model को देने वाले हैं, साथ में यह सवाल: "क्या आप जानेंगे कि इस tool को कब कॉल करना है?"
3. सटीक और दोहराने लायक आउटपुट के लिए Temperature को उसके डिफ़ॉल्ट 0.1 पर रहने दें। ब्रेनस्टॉर्मिंग के लिए इसे बढ़ाएँ।
4. लंबे जवाबों के लिए Max Tokens को 2048 पर रखें, या छोटे जवाबों के लिए इसे घटाएँ।
5. Top P, Presence Penalty और Frequency Penalty तभी बदलें जब आउटपुट लूप करे या दोहराव भरा लगे।
6. चलाएँ, बदलाव करें, फिर दोबारा चलाएँ। मॉडल पेज असीमित generations दिखाता है, इसलिए बार-बार प्रयोग करने की कोई लागत नहीं है।

💡 होस्टेड जवाब की तुलना अपने लोकल run से करें। अगर वे लगभग एक जैसे हों, तो आपका लोकल सेटअप अपना काम कर रहा है और आप होस्टेड call का पैसा देना बंद कर सकते हैं।

Bridge को इमेज जनरेशन के साथ जोड़ें

ask_local_model बन जाने के बाद, वह सिर्फ़ logs summarize करने से ज़्यादा कर सकता है। लोकल मॉडल इमेज prompts ड्राफ़्ट करने का एक सस्ता और निजी तरीका है, और यहीं bridge विज़ुअल काम से मिलता है।

एक तीसरा tool जोड़ें जो एक विषय लेकर 60 शब्दों का फ़ोटोग्राफ़िक prompt लौटाए: सब्जेक्ट, सेटिंग, रोशनी की दिशा, लेंस और फ़िल्म जैसा लुक। आपका assistant उसे कॉल करता है, और आप नतीजा एक टेक्स्ट-टू-इमेज मॉडल में डाल देते हैं। ड्राफ़्ट के लिए P-Image एक त्वरित विकल्प है। जब prompt को और विवरण चाहिए हो, तो दूसरे चरण के लिए FLUX 2 Pro ठीक रहता है।

एक सरल रूटीन अच्छा काम करता है:

1. स्थानीय मॉडल से एक ही सब्जेक्ट पर तीन प्रॉम्प्ट वैरिएशन माँगें।
2. तीनों जनरेट करें और सबसे अच्छा फ़्रेम रखें।
3. विजेता को PicassoIA मॉडल कैटलॉग से एक इमेज-टू-वीडियो मॉडल के साथ एनिमेट करें।

यही पैटर्न थंबनेल, प्रोडक्ट शॉट्स और ब्लॉग हेडर पर भी काम करता है। Bridge ड्राफ़्टिंग के चरण को मुफ़्त और निजी रखता है, और होस्टेड मॉडल भारी रेंडरिंग संभालते हैं।

PicassoIA पर अपनी इमेज बनाएँ

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

Prompt-drafting वाला विचार आज ही आज़माएँ। अपने लोकल मॉडल से एक फ़ोटोग्राफ़िक prompt माँगें, Picasso IA खोलें, और P-Image या FLUX 2 Pro से अपनी पहली इमेज जनरेट करें। लेंस, रोशनी की दिशा या सेटिंग बदलें, और फिर चलाएँ। जब कोई फ़्रेम अच्छा लगे, तो उसे एक छोटे वीडियो में बदलें। हर उपलब्ध मॉडल देखने के लिए पूरा PicassoIA catalog ब्राउज़ करें, और Picasso IA पर प्रयोग शुरू करें।