Skip to main content
Glama
enesjakozh
rawveg

Ollama MCP Server

by rawveg
OverviewInspectSchemaRelated ServersScoreDiscussions
TypeScript
Local

🦙 Ollama MCP Server

Supercharge your AI assistant with local LLM access

License: AGPL-3.0 TypeScript MCP Coverage

An MCP (Model Context Protocol) server that exposes the complete Ollama SDK as MCP tools, enabling seamless integration between your local LLM models and MCP-compatible applications like Claude Desktop and Cline.

Features • Installation • Available Tools • Configuration • Retry Behavior • Development

✨ Features

  • ☁️ Ollama Cloud Support - Full integration with Ollama's cloud platform

  • 🔧 14 Comprehensive Tools - Full access to Ollama's SDK functionality

  • 🔄 Hot-Swap Architecture - Automatic tool discovery with zero-config

  • 🎯 Type-Safe - Built with TypeScript and Zod validation

  • 📊 High Test Coverage - 96%+ coverage with comprehensive test suite

  • 🚀 Zero Dependencies - Minimal footprint, maximum performance

  • 🔌 Drop-in Integration - Works with Claude Desktop, Cline, and other MCP clients

  • 🌐 Web Search & Fetch - Real-time web search and content extraction via Ollama Cloud

  • 🔀 Hybrid Mode - Use local and cloud models seamlessly in one server

Related MCP server: MCP Ollama Server

💡 Level Up Your Ollama Experience with Claude Code and Desktop

The Complete Package: Tools + Knowledge

This MCP server gives Claude the tools to interact with Ollama - but you'll get even more value by also installing the Ollama Skill from the Skillsforge Marketplace:

  • 🚗 This MCP = The Car - All the tools and capabilities

  • 🎓 Ollama Skill = Driving Lessons - Expert knowledge on how to use them effectively

The Ollama Skill teaches Claude:

  • Best practices for model selection and configuration

  • Optimal prompting strategies for different Ollama models

  • When to use chat vs generate, embeddings, and other tools

  • Performance optimization and troubleshooting

  • Advanced features like tool calling and function support

Install both for the complete experience:

  1. ✅ This MCP server (tools)

  2. ✅ Ollama Skill (expertise)

Result: Claude doesn't just have the car - it knows how to drive! 🏎️

📦 Installation

Quick Start with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{ "mcpServers": { "ollama": { "command": "npx", "args": ["-y", "ollama-mcp"] } } }

Global Installation

npm install -g ollama-mcp

For Cline (VS Code)

Add to your Cline MCP settings (cline_mcp_settings.json):

{ "mcpServers": { "ollama": { "command": "npx", "args": ["-y", "ollama-mcp"] } } }

🛠️ Available Tools

Model Management

Tool

Description

ollama_list

List all available local models

ollama_show

Get detailed information about a specific model

ollama_pull

Download models from Ollama library

ollama_push

Push models to Ollama library

ollama_copy

Create a copy of an existing model

ollama_delete

Remove models from local storage

ollama_create

Create custom models from Modelfile

Model Operations

Tool

Description

ollama_ps

List currently running models

ollama_generate

Generate text completions

ollama_chat

Interactive chat with models (supports tools/functions)

ollama_embed

Generate embeddings for text

Web Tools (Ollama Cloud)

Tool

Description

ollama_web_search

Search the web with customizable result limits (requires

OLLAMA_API_KEY

)

ollama_web_fetch

Fetch and parse web page content (requires

OLLAMA_API_KEY

)

Note: Web tools require an Ollama Cloud API key. They connect to https://ollama.com/api for web search and fetch operations.

⚙️ Configuration

Environment Variables

Variable

Default

Description

OLLAMA_HOST

http://127.0.0.1:11434

Ollama server endpoint (use

https://ollama.com

for cloud)

OLLAMA_API_KEY

-

API key for Ollama Cloud (required for web tools and cloud models)

Custom Ollama Host

{ "mcpServers": { "ollama": { "command": "npx", "args": ["-y", "ollama-mcp"], "env": { "OLLAMA_HOST": "http://localhost:11434" } } } }

Ollama Cloud Configuration

To use Ollama's cloud platform with web search and fetch capabilities:

{ "mcpServers": { "ollama": { "command": "npx", "args": ["-y", "ollama-mcp"], "env": { "OLLAMA_HOST": "https://ollama.com", "OLLAMA_API_KEY": "your-ollama-cloud-api-key" } } } }

Cloud Features:

  • ☁️ Access cloud-hosted models

  • 🔍 Web search with ollama_web_search (requires API key)

  • 📄 Web fetch with ollama_web_fetch (requires API key)

  • 🚀 Faster inference on cloud infrastructure

Get your API key: Visit ollama.com to sign up and obtain your API key.

Hybrid Mode (Local + Cloud)

You can use both local and cloud models by pointing to your local Ollama instance while providing an API key:

{ "mcpServers": { "ollama": { "command": "npx", "args": ["-y", "ollama-mcp"], "env": { "OLLAMA_HOST": "http://127.0.0.1:11434", "OLLAMA_API_KEY": "your-ollama-cloud-api-key" } } } }

This configuration:

  • ✅ Runs local models from your Ollama instance

  • ✅ Enables cloud-only web search and fetch tools

  • ✅ Best of both worlds: privacy + web connectivity

🔄 Retry Behavior

The MCP server includes intelligent retry logic for handling transient failures when communicating with Ollama APIs:

Automatic Retry Strategy

Web Tools (

  • Automatically retry on rate limit errors (HTTP 429)

  • Maximum of 3 retry attempts (4 total requests including initial)

  • Request timeout: 30 seconds per request (prevents hung connections)

  • Respects the Retry-After header when provided by the API

  • Falls back to exponential backoff with jitter when Retry-After is not present

Retry-After Header Support

The server intelligently handles the standard HTTP Retry-After header in two formats:

1. Delay-Seconds Format:

Retry-After: 60

Waits exactly 60 seconds before retrying.

2. HTTP-Date Format:

Retry-After: Wed, 21 Oct 2025 07:28:00 GMT

Calculates delay until the specified timestamp.

Exponential Backoff

When Retry-After is not provided or invalid:

  • Initial delay: 1 second (default)

  • Maximum delay: 10 seconds (default, configurable)

  • Strategy: Exponential backoff with full jitter

  • Formula: random(0, min(initialDelay × 2^attempt, maxDelay))

Example retry delays:

  • 1st retry: 0-1 seconds

  • 2nd retry: 0-2 seconds

  • 3rd retry: 0-4 seconds (capped at 0-10s max)

Error Handling

Retried Errors (transient failures):

  • HTTP 429 (Too Many Requests) - rate limiting

  • HTTP 500 (Internal Server Error) - transient server issues

  • HTTP 502 (Bad Gateway) - gateway/proxy received invalid response

  • HTTP 503 (Service Unavailable) - server temporarily unable to handle request

  • HTTP 504 (Gateway Timeout) - gateway/proxy did not receive timely response

Non-Retried Errors (permanent failures):

  • Request timeouts (30 second limit exceeded)

  • Network timeouts (no status code)

  • Abort/cancel errors

  • HTTP 4xx errors (except 429) - client errors requiring changes

  • Other HTTP 5xx errors (501, 505, 506, 508, etc.) - configuration/implementation issues

The retry mechanism ensures robust handling of temporary API issues while respecting server-provided retry guidance and preventing excessive request rates. Transient 5xx errors (500, 502, 503, 504) are safe to retry for the idempotent POST operations used by ollama_web_search and ollama_web_fetch. Individual requests timeout after 30 seconds to prevent indefinitely hung connections.

🎯 Usage Examples

Chat with a Model

// MCP clients can invoke: { "tool": "ollama_chat", "arguments": { "model": "llama3.2:latest", "messages": [ { "role": "user", "content": "Explain quantum computing" } ] } }

Generate Embeddings

{ "tool": "ollama_embed", "arguments": { "model": "nomic-embed-text", "input": ["Hello world", "Embeddings are great"] } }

Web Search

{ "tool": "ollama_web_search", "arguments": { "query": "latest AI developments", "max_results": 5 } }

🏗️ Architecture

This server uses a hot-swap autoloader pattern:

src/ ├── index.ts # Entry point (27 lines) ├── server.ts # MCP server creation ├── autoloader.ts # Dynamic tool discovery └── tools/ # Tool implementations ├── chat.ts # Each exports toolDefinition ├── generate.ts └── ...

Key Benefits:

  • Add new tools by dropping files in src/tools/

  • Zero server code changes required

  • Each tool is independently testable

  • 100% function coverage on all tools

🧪 Development

Prerequisites

  • Node.js v16+

  • npm or pnpm

  • Ollama running locally

Setup

# Clone repository git clone https://github.com/rawveg/ollama-mcp.git cd ollama-mcp # Install dependencies npm install # Build project npm run build # Run tests npm test # Run tests with coverage npm run test:coverage

Test Coverage

Statements : 96.37% Branches : 84.82% Functions : 100% Lines : 96.37%

Adding a New Tool

  1. Create src/tools/your-tool.ts:

import { ToolDefinition } from '../autoloader.js'; import { Ollama } from 'ollama'; import { ResponseFormat } from '../types.js'; export const toolDefinition: ToolDefinition = { name: 'ollama_your_tool', description: 'Your tool description', inputSchema: { type: 'object', properties: { param: { type: 'string' } }, required: ['param'] }, handler: async (ollama, args, format) => { // Implementation return 'result'; } };

  1. Create tests in tests/tools/your-tool.test.ts

  2. Done! The autoloader discovers it automatically.

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Write tests - We maintain 96%+ coverage

  4. Commit with clear messages (git commit -m 'Add amazing feature')

  5. Push to your branch (git push origin feature/amazing-feature)

  6. Open a Pull Request

Code Quality Standards

  • All new tools must export toolDefinition

  • Maintain ≥80% test coverage

  • Follow existing TypeScript patterns

  • Use Zod schemas for input validation

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See LICENSE for details.

🔗 Related Projects

🙏 Acknowledgments

Built with:

  • Ollama SDK - Official Ollama JavaScript library

  • MCP SDK - Model Context Protocol SDK

  • Zod - TypeScript-first schema validation

⬆ back to top

Made with ❤️ by Tim Green

One-click Deploy
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rawveg/ollama-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server