{"id":30855188,"url":"https://github.com/andrewbrereton/claude-sidekick","last_synced_at":"2026-05-03T22:33:27.074Z","repository":{"id":308803505,"uuid":"1031599296","full_name":"andrewbrereton/claude-sidekick","owner":"andrewbrereton","description":"MCP server that connects Claude to local Ollama models, delegating simple tasks to save tokens for complex reasoning","archived":false,"fork":false,"pushed_at":"2025-08-12T01:56:59.000Z","size":10,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-02T02:28:33.767Z","etag":null,"topics":["claude-code","deepseek-coder","gpt-oss","llama","mcp-server","nomic-embed-text","ollama","qwen"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrewbrereton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-04T03:54:01.000Z","updated_at":"2026-02-26T12:07:28.000Z","dependencies_parsed_at":"2025-08-08T02:43:42.506Z","dependency_job_id":null,"html_url":"https://github.com/andrewbrereton/claude-sidekick","commit_stats":null,"previous_names":["andrewbrereton/claude-sidekick"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/andrewbrereton/claude-sidekick","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewbrereton%2Fclaude-sidekick","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewbrereton%2Fclaude-sidekick/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewbrereton%2Fclaude-sidekick/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewbrereton%2Fclaude-sidekick/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewbrereton","download_url":"https://codeload.github.com/andrewbrereton/claude-sidekick/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewbrereton%2Fclaude-sidekick/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32587819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"ssl_error","status_checked_at":"2026-05-03T22:09:10.534Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","deepseek-coder","gpt-oss","llama","mcp-server","nomic-embed-text","ollama","qwen"],"created_at":"2025-09-07T11:03:10.631Z","updated_at":"2026-05-03T22:33:27.067Z","avatar_url":"https://github.com/andrewbrereton.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Sidekick\n\nA Model Context Protocol (MCP) server that connects Claude to your local Ollama models, allowing you to offload simpler tasks and save your Claude tokens for complex work.\n\n## Quick Start\n\n### 1. Install Ollama\n\nFirst, install Ollama on your system:\n\n```bash\n# macOS\nbrew install ollama\n\n# Linux\ncurl -fsSL https://ollama.ai/install.sh | sh\n\n# Windows\n# Download from https://ollama.ai/download\n```\n\nStart Ollama:\n```bash\nollama serve\n```\n\n### 2. Pull Some Models\n\nDownload useful models for different tasks:\n\n```bash\n# General purpose models\nollama pull gpt-oss           # OpenAI's open-weight model\nollama pull llama3.2          # Fast, capable model\nollama pull qwen2.5           # High-quality text generation\n\n# Specialised models\nollama pull deepseek-coder    # Code generation\nollama pull nomic-embed-text  # Text embeddings\nollama pull llama3.2:1b       # Lightweight for simple tasks\n```\n\n### 3. Set Up the MCP Server\n\nCreate a new directory and install dependencies:\n\n```bash\nmkdir mcp-ollama-server\ncd mcp-ollama-server\n\n# Copy the files (index.ts, package.json, tsconfig.json)\n# Then install dependencies:\nnpm install\n\n# Create src directory and move index.ts there\nmkdir src\nmv index.ts src/\n\n# Build the project\nnpm run build\n```\n\n### 4. Configure Claude Desktop\n\nAdd the server to your Claude Desktop configuration:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"ollama\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/your/mcp-ollama-server/dist/index.js\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### 5. Restart Claude Desktop\n\nRestart Claude Desktop to load the new MCP server. You should see the Ollama tools available in Claude.\n\n## Available Tools\n\n### `ollama_generate_text`\nGenerate text for simple writing tasks, basic summaries, or straightforward content creation.\n\n**Best for:** Simple writing, basic explanations, content generation\n\n### `ollama_chat`\nHave conversations with local models for Q\u0026A, explanations, or dialogue-based tasks.\n\n**Best for:** Q\u0026A sessions, explanations, interactive tasks\n\n### `ollama_embed_text`\nGenerate text embeddings for semantic similarity, clustering, or search.\n\n**Best for:** Document similarity, semantic search, clustering\n\n### `ollama_code_generation`\nGenerate code using specialised coding models.\n\n**Best for:** Simple scripts, boilerplate code, basic programming tasks\n\n### `ollama_summarise`\nSummarise text content with different length options.\n\n**Best for:** Document summaries, article condensation\n\n### `ollama_list_models`\nList all available models on your Ollama installation.\n\n### `ollama_pull_model`\nDownload new models to Ollama.\n\n## Usage Examples\n\nOnce configured, Claude can use these tools like this:\n\n**Text Generation:**\n\u003e \"Use Ollama to generate a simple email template for customer onboarding\"\n\n**Code Generation:**\n\u003e \"Have DeepSeek Coder create a Python script to parse CSV files\"\n\n**Embeddings:**\n\u003e \"Generate embeddings for these document titles using Nomic\"\n\n**Summarisation:**\n\u003e \"Use Llama to create a brief summary of this article\"\n\n## Model Recommendations\n\n### For Text Generation\n- **gpt-oss** - Excellent balance of speed and quality\n- **llama3.2** - Good balance of speed and quality\n- **qwen2.5** - Higher quality but slower\n- **llama3.2:1b** - Very fast for simple tasks\n\n### For Coding\n- **gpt-oss** - Excellent code generation\n- **deepseek-coder** - Great code generation\n- **qwen2.5-coder** - Alternative coding model\n\n### For Embeddings\n- **nomic-embed-text** - Fast, high-quality embeddings\n- **mxbai-embed-large** - Larger embedding model\n\n## Configuration\n\n### Customising the Server\n\nEdit `src/index.ts` to modify:\n\n- **Base URL:** Change Ollama endpoint (default: `http://localhost:11434`)\n- **Timeout:** Adjust request timeout (default: 5 minutes)\n- **Default Models:** Modify which models are used by default\n- **Temperature Settings:** Adjust creativity/randomness\n\n### Environment Variables\n\nYou can override settings with environment variables:\n\n```bash\nexport OLLAMA_BASE_URL=http://localhost:11434\nexport OLLAMA_TIMEOUT=300000\n```\n\n## Troubleshooting\n\n### \"Failed to connect to Ollama\"\n1. Ensure Ollama is running: `ollama serve`\n2. Check if it's accessible: `curl http://localhost:11434/api/tags`\n3. Verify no firewall blocking port 11434\n\n### \"Model not found\"\n1. List available models: `ollama list`\n2. Pull the missing model: `ollama pull model-name`\n\n### \"MCP server not appearing in Claude\"\n1. Check the config file path is correct\n2. Verify the absolute path to the built JavaScript file\n3. Restart Claude Desktop completely\n4. Check Claude Desktop logs for errors\n\n### Performance Tips\n\n1. **Use smaller models for simple tasks:**\n   - `llama3.2:1b` for basic text generation\n   - `qwen2.5:0.5b` for very simple tasks\n\n2. **Keep frequently used models warm:**\n   ```bash\n   # Pre-load models to keep them in memory\n   ollama run llama3.2 \"hello\"\n   ollama run deepseek-coder \"print hello\"\n   ```\n\n3. **Adjust temperature based on task:**\n   - Low (0.1-0.3) for factual/coding tasks\n   - Medium (0.5-0.8) for creative writing\n   - High (0.9-1.2) for very creative tasks\n\n## Development\n\n### Running in Development\n\n```bash\nnpm run dev        # Run with hot reload\nnpm run watch      # Watch mode\nnpm run type-check # Check TypeScript types\nnpm run lint       # Lint code\n```\n\n### Adding New Tools\n\nTo add new capabilities:\n\n1. Define the tool in `setupHandlers()`\n2. Add the handler method\n3. Update the Ollama client if needed\n4. Rebuild and restart\n\n### Extending Model Support\n\nTo support new model types:\n\n1. Add model configuration in the constructor\n2. Create specific handler methods\n3. Add appropriate prompting strategies\n\n## Example Workflow\n\nHere's how you might use this in practice:\n\n1. **Initial analysis with Claude:** \"I need to analyse this dataset and create a comprehensive report\"\n\n2. **Delegate simple tasks:** \"Use Ollama to generate basic descriptions for each data column\"\n\n3. **Complex analysis with Claude:** Claude does the sophisticated statistical analysis and insights\n\n4. **Offload summarisation:** \"Use Llama to summarise each section of findings\"\n\n5. **Final review with Claude:** Claude assembles everything into a polished report\n\nThis approach maximises your Claude token efficiency while still getting comprehensive results.\n\n## Security Notes\n\n- This server runs locally and doesn't send data externally\n- All model inference happens on your machine\n- No API keys or external services required\n- Your data stays completely private\n\n## Contributing\n\nFeel free to extend this server with additional capabilities:\n- Image generation support\n- Model fine-tuning integration\n- Performance monitoring\n- Model switching strategies\n- Custom prompt templates","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewbrereton%2Fclaude-sidekick","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewbrereton%2Fclaude-sidekick","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewbrereton%2Fclaude-sidekick/lists"}