Ollama MCP Server

---

✨ 機能

• ☁️ Ollama Cloud 対応 - Ollama のクラウドプラットフォームと完全に連携します
• 🔧 14 種類の包括的なツール - Ollama SDK の機能すべてにアクセスできます
• 🔄 ホットスワップアーキテクチャ - 設定不要でツールを自動検出します
• 🎯 型安全 - TypeScript と Zod による検証を使用して構築されています
• 📊 高いテストカバレッジ - 包括的なテストスイートで 96% 以上のカバレッジを実現しています
• 🚀 依存関係ゼロ - 最小限のフットプリントで、最大限のパフォーマンスを実現します
• 🔌 そのまま使える連携機能 - Claude Desktop、Cline、その他の MCP クライアントで動作します
• 🌐 ウェブ検索と取得 - Ollama Cloud を通じてリアルタイムのウェブ検索とコンテンツ抽出を行います
• 🔀 ハイブリッドモード - ローカルモデルとクラウドモデルを 1 つのサーバーでシームレスに利用できます

💡 Claude Code と Desktop で Ollama をさらに活用

完全なパッケージ：ツールと知識

この MCP サーバーは、Claude に Ollama を操作するためのツールを提供します。Skillsforge Marketplace の Ollama Skill もインストールすると、さらに多くの価値が得られます。

• 🚗 この MCP ＝ 車 - すべてのツールと機能
• 🎓 Ollama Skill ＝ 運転レッスン - ツールを効果的に使うための専門知識

Ollama Skill は Claude に次のことを教えます。

• モデルの選択と設定に関するベストプラクティス
• Ollama の各モデルに適した最適なプロンプト戦略
• chat と generate、埋め込み、その他のツールを使い分けるタイミング
• パフォーマンスの最適化とトラブルシューティング
• ツール呼び出しや関数サポートなどの高度な機能

すべての機能を利用するには、両方をインストールしてください。

1. ✅ この MCP サーバー（ツール）
2. ✅ Ollama Skill（専門知識）

結果：Claude は車を持っているだけでなく、運転方法も知っています！🏎️

📦 インストール

Claude Desktop ですぐに使う

Claude Desktop の設定ファイル（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

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

グローバルインストール

npm install -g ollama-mcp

Cline 用（VS Code）

Cline の MCP 設定（cline_mcp_settings.json）に追加します。

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

🛠️ 利用可能なツール

モデル管理

ツール	説明
ollama_list	利用可能なすべてのローカルモデルを一覧表示します
ollama_show	特定のモデルに関する詳細情報を取得します
ollama_pull	Ollama ライブラリからモデルをダウンロードします
ollama_push	Ollama ライブラリにモデルをプッシュします
ollama_copy	既存のモデルのコピーを作成します
ollama_delete	ローカルストレージからモデルを削除します
ollama_create	Modelfile からカスタムモデルを作成します

モデル操作

ツール	説明
ollama_ps	現在実行中のモデルを一覧表示します
ollama_generate	テキスト補完を生成します
ollama_chat	モデルと対話形式でチャットします（ツール／関数に対応）
ollama_embed	テキストの埋め込みを生成します

Web ツール（Ollama Cloud）

ツール	説明
ollama_web_search	結果数をカスタマイズしてウェブを検索します（OLLAMA_API_KEY が必要です）
ollama_web_fetch	ウェブページのコンテンツを取得して解析します（OLLAMA_API_KEY が必要です）

注記： Web ツールには Ollama Cloud API キーが必要です。Web 検索と取得の操作には https://ollama.com/api に接続します。

⚙️ 設定

環境変数

変数	デフォルト	説明
OLLAMA_HOST	http://127.0.0.1:11434	Ollama サーバーのエンドポイント（クラウドを利用する場合は https://ollama.com を指定します）
OLLAMA_API_KEY	-	Ollama Cloud の API キー（Web ツールとクラウドモデルに必要です）

カスタム Ollama ホスト

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

Ollama Cloud の設定

Web 検索と取得機能を備えた Ollama のクラウドプラットフォームを利用するには：

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

クラウド機能：

• ☁️ クラウドでホストされているモデルにアクセスできます
• 🔍 ollama_web_search で Web を検索できます（API キーが必要です）
• 📄 ollama_web_fetch で Web コンテンツを取得できます（API キーが必要です）
• 🚀 クラウドインフラストラクチャで推論を高速化できます

API キーの取得： ollama.com にアクセスして登録し、API キーを取得してください。

ハイブリッドモード（ローカル + クラウド）

ローカルの Ollama インスタンスを指定しながら API キーを設定すると、ローカルモデルとクラウドモデルの両方を利用できます。

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

この設定では：

• ✅ Ollama インスタンスのローカルモデルを実行します
• ✅ クラウド専用の Web 検索・取得ツールを有効にします
• ✅ プライバシーと Web 接続の両方を活用できます

🔄 リトライ動作

MCP サーバーには、Ollama API との通信時に一時的な障害に対処するためのインテリジェントなリトライロジックが含まれています。

自動リトライ戦略

Web ツール（ollama_web_search と ollama_web_fetch）：

• レート制限エラー（HTTP 429）が発生した場合、自動的にリトライします
• 最大 3 回のリトライ（初回を含めて合計 4 回のリクエスト）
• リクエストタイムアウト： リクエストごとに 30 秒（接続がハングするのを防止します）
• API から Retry-After ヘッダーが提供された場合は、その値に従います
• Retry-After がない場合は、ジッターを伴う指数バックオフにフォールバックします

Retry-After ヘッダーのサポート

サーバーは、標準の HTTP Retry-After ヘッダーを次の 2 つの形式で適切に処理します。

1. 秒数形式：

Retry-After: 60

リトライする前に、正確に 60 秒待機します。

2. HTTP 日付形式：

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

指定されたタイムスタンプまでの待機時間を計算します。

指数バックオフ

Retry-After が提供されない場合、または無効な場合：

• 初期遅延： 1 秒（デフォルト）
• 最大遅延： 10 秒（デフォルト。設定可能）
• 戦略： フルジッターを伴う指数バックオフ
• 計算式： random(0, min(initialDelay × 2^attempt, maxDelay))

リトライ遅延の例：

• 1 回目のリトライ：0～1 秒
• 2 回目のリトライ：0～2 秒
• 3 回目のリトライ：0～4 秒（最大 0～10 秒に制限）

エラー処理

リトライ対象のエラー（一時的な障害）：

• HTTP 429（リクエスト過多）- レート制限
• HTTP 500（内部サーバーエラー）- 一時的なサーバーの問題
• HTTP 502（不正なゲートウェイ）- ゲートウェイ／プロキシが無効な応答を受信
• HTTP 503（サービス利用不可）- サーバーが一時的にリクエストを処理できない
• HTTP 504（ゲートウェイタイムアウト）- ゲートウェイ／プロキシが時間内に応答を受信できない

リトライ対象外のエラー（恒久的な障害）：

• リクエストのタイムアウト（30 秒の上限超過）
• ネットワークタイムアウト（ステータスコードなし）
• 中断／キャンセルエラー
• HTTP 4xx エラー（429 を除く）- 変更が必要なクライアントエラー
• その他の HTTP 5xx エラー（501、505、506、508 など）- 設定／実装上の問題

リトライ機構により、サーバーが提供するリトライ指示に従い、過剰なリクエストを防ぎながら、一時的な API の問題に堅牢に対処できます。一時的な 5xx エラー（500、502、503、504）は、ollama_web_search と ollama_web_fetch で使用される冪等な POST 操作であれば、安全にリトライできます。接続が無期限にハングするのを防ぐため、個々のリクエストは 30 秒でタイムアウトします。

🎯 使用例

モデルとのチャット

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

埋め込みの生成

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

Web 検索

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

🏗️ アーキテクチャ

このサーバーでは、ホットスワップ対応のオートローダーパターンを使用しています。

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
    └── ...

主なメリット：

• src/tools/ にファイルを追加するだけで、新しいツールを追加できます
• サーバーコードを変更する必要はありません
• 各ツールを個別にテストできます
• すべてのツールで関数カバレッジ 100％を実現しています

🧪 開発

前提条件

• Node.js v16+
• npm または pnpm
• ローカルで Ollama が稼働していること

セットアップ

# 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

テストカバレッジ

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

新しいツールの追加

1. 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';
  }
};

2. tests/tools/your-tool.test.ts にテストを作成します。
3. 完了です！オートローダーが自動的に検出します。

🤝 コントリビューション

コントリビューションを歓迎します！次のガイドラインに従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. テストを作成します。カバレッジ 96％以上を維持しています
4. 明確なメッセージでコミットします（git commit -m 'Add amazing feature'）
5. ブランチにプッシュします（git push origin feature/amazing-feature）
6. プルリクエストを作成します

コード品質基準

• すべての新しいツールで toolDefinition をエクスポートする必要があります
• テストカバレッジ 80％以上を維持してください
• 既存の TypeScript のパターンに従ってください
• 入力の検証には Zod スキーマを使用してください

📄 ライセンス

このプロジェクトは GNU Affero General Public License v3.0（AGPL-3.0）の下でライセンスされています。

詳細は LICENSE を参照してください。

🔗 関連プロジェクト

• Skillsforge Marketplace - Ollama Skill を含む Claude Code スキル
• Ollama - 大規模言語モデルをローカルで使い始めるためのプロジェクト
• Model Context Protocol - AI アシスタント連携のためのオープン標準
• Claude Desktop - Anthropic のデスクトップアプリケーション
• Cline - VS Code 向け AI アシスタント

🙏 謝辞

以下を使用して構築しました：

• Ollama SDK - Ollama の公式 JavaScript ライブラリ
• MCP SDK - Model Context Protocol SDK
• Zod - TypeScript を優先したスキーマ検証

---