Back to search
ollama-mcp
SkillGitHub
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
Markdown
[](/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)
- <div align="center">
- # 🦙 Ollama MCP Server
- **Supercharge your AI assistant with local LLM access**
- [](https://www.gnu.org/licenses/agpl-3.0)
- [](https://www.typescriptlang.org/)
- [](https://github.com/anthropics/model-context-protocol)
- [](https://github.com/rawveg/ollama-mcp)
- 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](#-features) • [Installation](#-installation) • [Available Tools](#-available-tools) • [Configuration](#-configuration) • [Retry Behavior](#-retry-behavior) • [Development](#-development)
- </div>
- ---
- ## ✨ 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
- ## 💡 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](https://github.com/rawveg/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](https://github.com/rawveg/skillsforge-marketplace) (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):
- ```json
- {
- "mcpServers": {
- "ollama": {
- "command": "npx",
- "args": ["-y", "ollama-mcp"]
- }
- }
- }
- ```
- ### Global Installation
- ```bash
- npm install -g ollama-mcp
- ```
- ### For Cline (VS Code)
- Add to your Cline MCP settings (`cline_mcp_settings.json`):
- ```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
- ```json
- {
- "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:
- ```json
- {
- "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](https://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:
- ```json
- {
- "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 (`ollama_web_search` and `ollama_web_fetch`):**
- - 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
- ```typescript
- // MCP clients can invoke:
- {
- "tool": "ollama_chat",
- "arguments": {
- "model": "llama3.2:latest",
- "messages": [
- { "role": "user", "content": "Explain quantum computing" }
- ]
- }
- }
- ```
- ### Generate Embeddings
- ```typescript
- {
- "tool": "ollama_embed",
- "arguments": {
- "model": "nomic-embed-text",
- "input": ["Hello world", "Embeddings are great"]
- }
- }
- ```
- ### Web Search
- ```typescript
- {
- "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
- ```bash
- # 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`:
- ```typescript
- 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';
- }
- };
- ```
- 2. Create tests in `tests/tools/your-tool.test.ts`
- 3. 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](LICENSE) for details.
- ## 🔗 Related Projects
- - [Skillsforge Marketplace](https://github.com/rawveg/skillsforge-marketplace) - Claude Code skills including the Ollama Skill
- - [Ollama](https://ollama.ai) - Get up and running with large language models locally
- - [Model Context Protocol](https://github.com/anthropics/model-context-protocol) - Open standard for AI assistant integration
- - [Claude Desktop](https://claude.ai/desktop) - Anthropic's desktop application
- - [Cline](https://github.com/cline/cline) - VS Code AI assistant
- ## 🙏 Acknowledgments
- Built with:
- - [Ollama SDK](https://github.com/ollama/ollama-js) - Official Ollama JavaScript library
- - [MCP SDK](https://github.com/anthropics/model-context-protocol) - Model Context Protocol SDK
- - [Zod](https://zod.dev) - TypeScript-first schema validation
- ---
- <div align="center">
- **[⬆ back to top](#-ollama-mcp-server)**
- Made with ❤️ by [Tim Green](https://github.com/rawveg)
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.