Skip to content
Back to search

ollama-mcp

An MCP Server for Ollama

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rawveg--ollama-mcp/badge.svg)](/listings/rawveg--ollama-mcp)

HTML

<a href="/listings/rawveg--ollama-mcp"><img src="/api/listings/rawveg--ollama-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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"]
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 432 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # 🦙 Ollama MCP Server
  3. **Supercharge your AI assistant with local LLM access**
  4. [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
  5. [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
  6. [![MCP](https://img.shields.io/badge/MCP-1.0-green)](https://github.com/anthropics/model-context-protocol)
  7. [![Coverage](https://img.shields.io/badge/Coverage-96%25-brightgreen)](https://github.com/rawveg/ollama-mcp)
  8. 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.
  9. [Features](#-features) • [Installation](#-installation) • [Available Tools](#-available-tools) • [Configuration](#-configuration) • [Retry Behavior](#-retry-behavior) • [Development](#-development)
  10. </div>
  11. ---
  12. ## ✨ Features
  13. - ☁️ **Ollama Cloud Support** - Full integration with Ollama's cloud platform
  14. - 🔧 **14 Comprehensive Tools** - Full access to Ollama's SDK functionality
  15. - 🔄 **Hot-Swap Architecture** - Automatic tool discovery with zero-config
  16. - 🎯 **Type-Safe** - Built with TypeScript and Zod validation
  17. - 📊 **High Test Coverage** - 96%+ coverage with comprehensive test suite
  18. - 🚀 **Zero Dependencies** - Minimal footprint, maximum performance
  19. - 🔌 **Drop-in Integration** - Works with Claude Desktop, Cline, and other MCP clients
  20. - 🌐 **Web Search & Fetch** - Real-time web search and content extraction via Ollama Cloud
  21. - 🔀 **Hybrid Mode** - Use local and cloud models seamlessly in one server
  22. ## 💡 Level Up Your Ollama Experience with Claude Code and Desktop
  23. ### The Complete Package: Tools + Knowledge
  24. 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](https://github.com/rawveg/skillsforge-marketplace):
  25. - 🚗 **This MCP = The Car** - All the tools and capabilities
  26. - 🎓 **Ollama Skill = Driving Lessons** - Expert knowledge on how to use them effectively
  27. The Ollama Skill teaches Claude:
  28. - Best practices for model selection and configuration
  29. - Optimal prompting strategies for different Ollama models
  30. - When to use chat vs generate, embeddings, and other tools
  31. - Performance optimization and troubleshooting
  32. - Advanced features like tool calling and function support
  33. **Install both for the complete experience:**
  34. 1. ✅ This MCP server (tools)
  35. 2. ✅ [Ollama Skill](https://github.com/rawveg/skillsforge-marketplace) (expertise)
  36. Result: Claude doesn't just have the car - it knows how to drive! 🏎️
  37. ## 📦 Installation
  38. ### Quick Start with Claude Desktop
  39. Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
  40. ```json
  41. {
  42. "mcpServers": {
  43. "ollama": {
  44. "command": "npx",
  45. "args": ["-y", "ollama-mcp"]
  46. }
  47. }
  48. }
  49. ```
  50. ### Global Installation
  51. ```bash
  52. npm install -g ollama-mcp
  53. ```
  54. ### For Cline (VS Code)
  55. Add to your Cline MCP settings (`cline_mcp_settings.json`):
  56. ```json
  57. {
  58. "mcpServers": {
  59. "ollama": {
  60. "command": "npx",
  61. "args": ["-y", "ollama-mcp"]
  62. }
  63. }
  64. }
  65. ```
  66. ## 🛠️ Available Tools
  67. ### Model Management
  68. | Tool | Description |
  69. |------|-------------|
  70. | `ollama_list` | List all available local models |
  71. | `ollama_show` | Get detailed information about a specific model |
  72. | `ollama_pull` | Download models from Ollama library |
  73. | `ollama_push` | Push models to Ollama library |
  74. | `ollama_copy` | Create a copy of an existing model |
  75. | `ollama_delete` | Remove models from local storage |
  76. | `ollama_create` | Create custom models from Modelfile |
  77. ### Model Operations
  78. | Tool | Description |
  79. |------|-------------|
  80. | `ollama_ps` | List currently running models |
  81. | `ollama_generate` | Generate text completions |
  82. | `ollama_chat` | Interactive chat with models (supports tools/functions) |
  83. | `ollama_embed` | Generate embeddings for text |
  84. ### Web Tools (Ollama Cloud)
  85. | Tool | Description |
  86. |------|-------------|
  87. | `ollama_web_search` | Search the web with customizable result limits (requires `OLLAMA_API_KEY`) |
  88. | `ollama_web_fetch` | Fetch and parse web page content (requires `OLLAMA_API_KEY`) |
  89. > **Note:** Web tools require an Ollama Cloud API key. They connect to `https://ollama.com/api` for web search and fetch operations.
  90. ## ⚙️ Configuration
  91. ### Environment Variables
  92. | Variable | Default | Description |
  93. |----------|---------|-------------|
  94. | `OLLAMA_HOST` | `http://127.0.0.1:11434` | Ollama server endpoint (use `https://ollama.com` for cloud) |
  95. | `OLLAMA_API_KEY` | - | API key for Ollama Cloud (required for web tools and cloud models) |
  96. ### Custom Ollama Host
  97. ```json
  98. {
  99. "mcpServers": {
  100. "ollama": {
  101. "command": "npx",
  102. "args": ["-y", "ollama-mcp"],
  103. "env": {
  104. "OLLAMA_HOST": "http://localhost:11434"
  105. }
  106. }
  107. }
  108. }
  109. ```
  110. ### Ollama Cloud Configuration
  111. To use Ollama's cloud platform with web search and fetch capabilities:
  112. ```json
  113. {
  114. "mcpServers": {
  115. "ollama": {
  116. "command": "npx",
  117. "args": ["-y", "ollama-mcp"],
  118. "env": {
  119. "OLLAMA_HOST": "https://ollama.com",
  120. "OLLAMA_API_KEY": "your-ollama-cloud-api-key"
  121. }
  122. }
  123. }
  124. }
  125. ```
  126. **Cloud Features:**
  127. - ☁️ Access cloud-hosted models
  128. - 🔍 Web search with `ollama_web_search` (requires API key)
  129. - 📄 Web fetch with `ollama_web_fetch` (requires API key)
  130. - 🚀 Faster inference on cloud infrastructure
  131. **Get your API key:** Visit [ollama.com](https://ollama.com) to sign up and obtain your API key.
  132. ### Hybrid Mode (Local + Cloud)
  133. You can use both local and cloud models by pointing to your local Ollama instance while providing an API key:
  134. ```json
  135. {
  136. "mcpServers": {
  137. "ollama": {
  138. "command": "npx",
  139. "args": ["-y", "ollama-mcp"],
  140. "env": {
  141. "OLLAMA_HOST": "http://127.0.0.1:11434",
  142. "OLLAMA_API_KEY": "your-ollama-cloud-api-key"
  143. }
  144. }
  145. }
  146. }
  147. ```
  148. This configuration:
  149. - ✅ Runs local models from your Ollama instance
  150. - ✅ Enables cloud-only web search and fetch tools
  151. - ✅ Best of both worlds: privacy + web connectivity
  152. ## 🔄 Retry Behavior
  153. The MCP server includes intelligent retry logic for handling transient failures when communicating with Ollama APIs:
  154. ### Automatic Retry Strategy
  155. **Web Tools (`ollama_web_search` and `ollama_web_fetch`):**
  156. - Automatically retry on rate limit errors (HTTP 429)
  157. - Maximum of **3 retry attempts** (4 total requests including initial)
  158. - **Request timeout:** 30 seconds per request (prevents hung connections)
  159. - Respects the `Retry-After` header when provided by the API
  160. - Falls back to exponential backoff with jitter when `Retry-After` is not present
  161. ### Retry-After Header Support
  162. The server intelligently handles the standard HTTP `Retry-After` header in two formats:
  163. **1. Delay-Seconds Format:**
  164. ```
  165. Retry-After: 60
  166. ```
  167. Waits exactly 60 seconds before retrying.
  168. **2. HTTP-Date Format:**
  169. ```
  170. Retry-After: Wed, 21 Oct 2025 07:28:00 GMT
  171. ```
  172. Calculates delay until the specified timestamp.
  173. ### Exponential Backoff
  174. When `Retry-After` is not provided or invalid:
  175. - **Initial delay:** 1 second (default)
  176. - **Maximum delay:** 10 seconds (default, configurable)
  177. - **Strategy:** Exponential backoff with full jitter
  178. - **Formula:** `random(0, min(initialDelay × 2^attempt, maxDelay))`
  179. **Example retry delays:**
  180. - 1st retry: 0-1 seconds
  181. - 2nd retry: 0-2 seconds
  182. - 3rd retry: 0-4 seconds (capped at 0-10s max)
  183. ### Error Handling
  184. **Retried Errors (transient failures):**
  185. - HTTP 429 (Too Many Requests) - rate limiting
  186. - HTTP 500 (Internal Server Error) - transient server issues
  187. - HTTP 502 (Bad Gateway) - gateway/proxy received invalid response
  188. - HTTP 503 (Service Unavailable) - server temporarily unable to handle request
  189. - HTTP 504 (Gateway Timeout) - gateway/proxy did not receive timely response
  190. **Non-Retried Errors (permanent failures):**
  191. - Request timeouts (30 second limit exceeded)
  192. - Network timeouts (no status code)
  193. - Abort/cancel errors
  194. - HTTP 4xx errors (except 429) - client errors requiring changes
  195. - Other HTTP 5xx errors (501, 505, 506, 508, etc.) - configuration/implementation issues
  196. 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.
  197. ## 🎯 Usage Examples
  198. ### Chat with a Model
  199. ```typescript
  200. // MCP clients can invoke:
  201. {
  202. "tool": "ollama_chat",
  203. "arguments": {
  204. "model": "llama3.2:latest",
  205. "messages": [
  206. { "role": "user", "content": "Explain quantum computing" }
  207. ]
  208. }
  209. }
  210. ```
  211. ### Generate Embeddings
  212. ```typescript
  213. {
  214. "tool": "ollama_embed",
  215. "arguments": {
  216. "model": "nomic-embed-text",
  217. "input": ["Hello world", "Embeddings are great"]
  218. }
  219. }
  220. ```
  221. ### Web Search
  222. ```typescript
  223. {
  224. "tool": "ollama_web_search",
  225. "arguments": {
  226. "query": "latest AI developments",
  227. "max_results": 5
  228. }
  229. }
  230. ```
  231. ## 🏗️ Architecture
  232. This server uses a **hot-swap autoloader** pattern:
  233. ```
  234. src/
  235. ├── index.ts # Entry point (27 lines)
  236. ├── server.ts # MCP server creation
  237. ├── autoloader.ts # Dynamic tool discovery
  238. └── tools/ # Tool implementations
  239. ├── chat.ts # Each exports toolDefinition
  240. ├── generate.ts
  241. └── ...
  242. ```
  243. **Key Benefits:**
  244. - Add new tools by dropping files in `src/tools/`
  245. - Zero server code changes required
  246. - Each tool is independently testable
  247. - 100% function coverage on all tools
  248. ## 🧪 Development
  249. ### Prerequisites
  250. - Node.js v16+
  251. - npm or pnpm
  252. - Ollama running locally
  253. ### Setup
  254. ```bash
  255. # Clone repository
  256. git clone https://github.com/rawveg/ollama-mcp.git
  257. cd ollama-mcp
  258. # Install dependencies
  259. npm install
  260. # Build project
  261. npm run build
  262. # Run tests
  263. npm test
  264. # Run tests with coverage
  265. npm run test:coverage
  266. ```
  267. ### Test Coverage
  268. ```
  269. Statements : 96.37%
  270. Branches : 84.82%
  271. Functions : 100%
  272. Lines : 96.37%
  273. ```
  274. ### Adding a New Tool
  275. 1. Create `src/tools/your-tool.ts`:
  276. ```typescript
  277. import { ToolDefinition } from '../autoloader.js';
  278. import { Ollama } from 'ollama';
  279. import { ResponseFormat } from '../types.js';
  280. export const toolDefinition: ToolDefinition = {
  281. name: 'ollama_your_tool',
  282. description: 'Your tool description',
  283. inputSchema: {
  284. type: 'object',
  285. properties: {
  286. param: { type: 'string' }
  287. },
  288. required: ['param']
  289. },
  290. handler: async (ollama, args, format) => {
  291. // Implementation
  292. return 'result';
  293. }
  294. };
  295. ```
  296. 2. Create tests in `tests/tools/your-tool.test.ts`
  297. 3. Done! The autoloader discovers it automatically.
  298. ## 🤝 Contributing
  299. Contributions are welcome! Please follow these guidelines:
  300. 1. **Fork** the repository
  301. 2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
  302. 3. **Write tests** - We maintain 96%+ coverage
  303. 4. **Commit** with clear messages (`git commit -m 'Add amazing feature'`)
  304. 5. **Push** to your branch (`git push origin feature/amazing-feature`)
  305. 6. **Open** a Pull Request
  306. ### Code Quality Standards
  307. - All new tools must export `toolDefinition`
  308. - Maintain ≥80% test coverage
  309. - Follow existing TypeScript patterns
  310. - Use Zod schemas for input validation
  311. ## 📄 License
  312. This project is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0).
  313. See [LICENSE](LICENSE) for details.
  314. ## 🔗 Related Projects
  315. - [Skillsforge Marketplace](https://github.com/rawveg/skillsforge-marketplace) - Claude Code skills including the Ollama Skill
  316. - [Ollama](https://ollama.ai) - Get up and running with large language models locally
  317. - [Model Context Protocol](https://github.com/anthropics/model-context-protocol) - Open standard for AI assistant integration
  318. - [Claude Desktop](https://claude.ai/desktop) - Anthropic's desktop application
  319. - [Cline](https://github.com/cline/cline) - VS Code AI assistant
  320. ## 🙏 Acknowledgments
  321. Built with:
  322. - [Ollama SDK](https://github.com/ollama/ollama-js) - Official Ollama JavaScript library
  323. - [MCP SDK](https://github.com/anthropics/model-context-protocol) - Model Context Protocol SDK
  324. - [Zod](https://zod.dev) - TypeScript-first schema validation
  325. ---
  326. <div align="center">
  327. **[⬆ back to top](#-ollama-mcp-server)**
  328. Made with ❤️ by [Tim Green](https://github.com/rawveg)
  329. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.