{"id":43100320,"url":"https://github.com/ximot/knowledge-mcp","last_synced_at":"2026-01-31T17:11:47.630Z","repository":{"id":334902551,"uuid":"1143279214","full_name":"ximot/knowledge-mcp","owner":"ximot","description":"Self-hosted RAG knowledge base for AI coding assistants. MCP server with Qdrant + Ollama embeddings.","archived":false,"fork":false,"pushed_at":"2026-01-27T19:53:42.000Z","size":168,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-28T00:10:28.576Z","etag":null,"topics":["ai-tools","claude-code","knowledge-base","mcp","ollama","qdrant","rag","vector-database"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ximot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-27T11:38:30.000Z","updated_at":"2026-01-27T18:10:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ximot/knowledge-mcp","commit_stats":null,"previous_names":["ximot/knowledge-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ximot/knowledge-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ximot%2Fknowledge-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ximot%2Fknowledge-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ximot%2Fknowledge-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ximot%2Fknowledge-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ximot","download_url":"https://codeload.github.com/ximot/knowledge-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ximot%2Fknowledge-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28948358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T14:26:55.697Z","status":"ssl_error","status_checked_at":"2026-01-31T14:26:52.545Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["ai-tools","claude-code","knowledge-base","mcp","ollama","qdrant","rag","vector-database"],"created_at":"2026-01-31T17:11:46.899Z","updated_at":"2026-01-31T17:11:47.618Z","avatar_url":"https://github.com/ximot.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Knowledge MCP Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker\u0026logoColor=white)](docker-compose.yml)\n[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python\u0026logoColor=white)](https://python.org)\n\nA self-hosted **RAG (Retrieval-Augmented Generation) knowledge base** for AI coding assistants. Store knowledge entries, reusable skills (prompts), project metadata, and private notes in a vector database. Access everything via [MCP (Model Context Protocol)](https://modelcontextprotocol.io/).\n\nWorks with **Claude Code**, **OpenCode**, and any MCP-compatible client. Powered by **Qdrant** + **Ollama** embeddings.\n\n## Architecture\n\n```\n┌──────────────┐  ┌──────────────┐  ┌──────────────┐\n│ Claude Code  │  │   OpenCode   │  │  MCP Client  │\n└──────┬───────┘  └──────┬───────┘  └──────┬───────┘\n       │                 │                 │\n       └─────────────────┼─────────────────┘\n                         │ MCP (stdio / HTTP+SSE)\n                         ▼\n              ┌─────────────────────┐\n              │  Knowledge MCP      │\n              │  Server (:8765)     │\n              └──┬──────────────┬───┘\n                 │              │\n        ┌────────▼───┐  ┌──────▼──────┐\n        │   Qdrant   │  │   Ollama    │\n        │   (:6333)  │  │  (:11434)   │\n        │ Vector DB  │  │ Embeddings  │\n        └────────────┘  └─────────────┘\n```\n\n**Data flow:** MCP tool call → Pydantic validation → Ollama embeddings → Qdrant vector search/storage\n\n**Collections:** Four Qdrant collections with cosine similarity:\n- `knowledge` — documentation, how-tos, code snippets, references\n- `skills` — reusable prompts and instructions\n- `projects` — project metadata (name, path, description, status)\n- `private` — personal notes, context, preferences\n\n## Quick Start\n\n### Docker (recommended)\n\n**Prerequisites:** Docker and Docker Compose installed.\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/ximot/knowledge-mcp.git\ncd knowledge-mcp\n\n# 2. (Optional) Copy and edit config\ncp .env.example .env\n\n# 3. Start all services\ndocker compose up -d\n```\n\n### Local with uv (recommended for development)\n\n**Prerequisites:** [uv](https://docs.astral.sh/uv/) installed, Qdrant and Ollama running.\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/ximot/knowledge-mcp.git\ncd knowledge-mcp\n\n# 2. Install dependencies\nuv sync\n\n# 3. Run the MCP server\nuv run python -m knowledge_mcp\n```\n\n### Local with pip (alternative)\n\n```bash\ngit clone https://github.com/ximot/knowledge-mcp.git\ncd knowledge-mcp\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\npython -m knowledge_mcp\n```\n\nThis starts three containers:\n- **knowledge-mcp** — MCP server on port `8765`\n- **qdrant** — vector database on port `6333`\n- **ollama** — embedding model on port `11434` (auto-pulls `nomic-embed-text` on first start)\n\nVerify everything is running:\n\n```bash\ncurl http://localhost:8765/health\n# {\"status\":\"ok\",\"qdrant\":true,\"ollama\":true,\"model\":\"nomic-embed-text\"}\n```\n\n## Configuration Reference\n\nAll settings are configured via environment variables. Set them in a `.env` file or export directly.\n\n| Variable | Default | Description |\n|---|---|---|\n| `QDRANT_HOST` | `localhost` | Qdrant server hostname |\n| `QDRANT_PORT` | `6333` | Qdrant REST API port |\n| `QDRANT_API_KEY` | _(empty)_ | API key for Qdrant Cloud or secured instances |\n| `QDRANT_HTTPS` | `false` | Use HTTPS for Qdrant connection |\n| `OLLAMA_HOST` | `http://localhost:11434` | Full Ollama server URL |\n| `EMBEDDING_MODEL` | `nomic-embed-text` | Ollama embedding model name |\n| `VECTOR_SIZE` | `768` | Embedding vector dimensions (must match model) |\n| `MCP_HOST` | `0.0.0.0` | HTTP server bind address |\n| `MCP_PORT` | `8765` | HTTP server port |\n\n\u003e When using `docker-compose.yml` (all-in-one), `QDRANT_HOST` and `OLLAMA_HOST` are automatically set to the container service names (`qdrant` and `http://ollama:11434`).\n\n## MCP Tools Reference\n\nThe server exposes 24 tools across four collections. All tools support `markdown` (default) and `json` response formats.\n\n### Knowledge\n\n| Tool | Description |\n|---|---|\n| `knowledge_search` | Semantic search across knowledge entries. Filters: `knowledge_type`, `tags` |\n| `knowledge_add` | Add a new entry (title, content, type, tags, source, metadata) |\n| `knowledge_get` | Retrieve a single entry by ID |\n| `knowledge_update` | Update fields of an existing entry (re-embeds on content change) |\n| `knowledge_delete` | Permanently delete an entry by ID |\n| `knowledge_list` | List entries with pagination and optional type/tag filters |\n\nKnowledge types: `note`, `documentation`, `code_snippet`, `reference`, `howto`, `other`\n\n### Skills\n\n| Tool | Description |\n|---|---|\n| `skill_search` | Semantic search across skills |\n| `skill_add` | Add a new skill (name, description, prompt, tags, version, examples) |\n| `skill_get` | Retrieve a skill by exact name (includes full prompt) |\n| `skill_update` | Update skill fields |\n| `skill_delete` | Permanently delete a skill by name |\n| `skill_list` | List all skills (names and descriptions, no prompts) |\n\nSkill names must match: `^[a-z0-9][a-z0-9-]*[a-z0-9]$` (lowercase alphanumeric with hyphens)\n\n### Projects\n\n| Tool | Description |\n|---|---|\n| `project_search` | Semantic search for projects. Filters: `status`, `tags` |\n| `project_add` | Add a project (name, path, description, status, tags, metadata) |\n| `project_get` | Retrieve a project by exact name |\n| `project_update` | Update project fields |\n| `project_delete` | Permanently delete a project by name |\n| `project_list` | List projects with pagination and status/tag filters |\n\nProject statuses: `active`, `archived`, `planned`\n\n### Private\n\n| Tool | Description |\n|---|---|\n| `private_search` | Semantic search across private entries. Filters: `private_type`, `tags` |\n| `private_add` | Add a private entry (title, content, type, tags, metadata) |\n| `private_get` | Retrieve a private entry by ID |\n| `private_update` | Update private entry fields |\n| `private_delete` | Permanently delete a private entry by ID |\n| `private_list` | List private entries with pagination and type/tag filters |\n\nPrivate types: `note`, `context`, `preference`, `secret_ref`\n\n## Usage with Claude Code\n\n### Option 1: HTTP/SSE (recommended for Docker)\n\nAdd to `~/.claude/settings.json` or your project's `.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"knowledge\": {\n      \"url\": \"http://localhost:8765/mcp\"\n    }\n  }\n}\n```\n\n### Option 2: stdio (local Python)\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"knowledge\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"knowledge_mcp.server\"],\n      \"cwd\": \"/path/to/knowledge-mcp\",\n      \"env\": {\n        \"QDRANT_HOST\": \"localhost\",\n        \"OLLAMA_HOST\": \"http://localhost:11434\"\n      }\n    }\n  }\n}\n```\n\n## Usage with Other Clients\n\n### OpenCode\n\nAdd to your OpenCode MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"knowledge\": {\n      \"url\": \"http://localhost:8765/mcp\"\n    }\n  }\n}\n```\n\n### Generic MCP Client\n\nThe server supports two transports:\n\n- **stdio** — run `python -m knowledge_mcp.server` as a subprocess\n- **HTTP (Streamable HTTP)** — connect to `http://\u003chost\u003e:8765/mcp`\n\nThe HTTP mode is stateless (`stateless_http=True`), so multiple clients can connect simultaneously.\n\n## Advanced\n\n### External Qdrant and Ollama\n\nIf you already have Qdrant and Ollama running (on your host, another server, or Qdrant Cloud), use the external compose file:\n\n```bash\n# Set connection details\nexport QDRANT_HOST=your-qdrant-host\nexport OLLAMA_HOST=http://your-ollama-host:11434\n\n# Start only the MCP server\ndocker compose -f docker-compose.external.yml up -d\n```\n\n**Qdrant Cloud example:**\n\n```env\nQDRANT_HOST=abc123.us-east4-0.gcp.cloud.qdrant.io\nQDRANT_PORT=6333\nQDRANT_API_KEY=your-api-key-here\nQDRANT_HTTPS=true\nOLLAMA_HOST=http://localhost:11434\n```\n\n### Custom Embedding Models\n\nYou can use any Ollama-compatible embedding model. Change the model and update the vector size accordingly:\n\n```env\nEMBEDDING_MODEL=mxbai-embed-large\nVECTOR_SIZE=1024\n```\n\n\u003e Make sure to pull the model first: `ollama pull mxbai-embed-large`\n\u003e\n\u003e Changing the embedding model requires re-indexing all existing data since vector dimensions and semantics will differ.\n\n### Importing Skills from SKILL.md Files\n\nBulk import skills from markdown files:\n\n```bash\n# Import all SKILL.md files from a directory (recursive)\npython scripts/import_skills.py /path/to/skills/directory\n\n# Import a single file\npython scripts/import_skills.py /path/to/SKILL.md\n```\n\nSKILL.md format with optional YAML frontmatter:\n\n```markdown\n---\nname: code-reviewer\ndescription: Expert code reviewer for quality analysis\ntags: [coding, review]\n---\n\nYou are an expert code reviewer. Analyze code for:\n1. Logic errors\n2. Security issues\n3. Performance problems\n...\n```\n\n### Health Check\n\nThe HTTP server exposes a `/health` endpoint that verifies connectivity to both Qdrant and Ollama:\n\n```bash\ncurl http://localhost:8765/health\n```\n\n```json\n{\n  \"status\": \"ok\",\n  \"qdrant\": true,\n  \"ollama\": true,\n  \"model\": \"nomic-embed-text\"\n}\n```\n\nStatus is `\"ok\"` when both backends are reachable, `\"degraded\"` otherwise (returns HTTP 503).\n\n## Development\n\n### Local Setup (uv — recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/ximot/knowledge-mcp.git\ncd knowledge-mcp\n\n# Install all dependencies (including dev tools: ruff, mypy)\nuv sync --extra dev\n\n# Start Qdrant (if not running)\ndocker run -d --name qdrant -p 6333:6333 qdrant/qdrant\n\n# Ensure Ollama has the embedding model\nollama pull nomic-embed-text\n\n# Run in stdio mode\nuv run python -m knowledge_mcp.server\n\n# Run in HTTP mode\nuv run python knowledge_mcp/http_server.py\n\n# Lint and format\nuv run ruff check --fix .\nuv run ruff format .\n```\n\n### Local Setup (pip — alternative)\n\n```bash\ngit clone https://github.com/ximot/knowledge-mcp.git\ncd knowledge-mcp\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n\npython -m knowledge_mcp.server\n```\n\n### Project Structure\n\n```\nknowledge-mcp/\n├── knowledge_mcp/\n│   ├── __init__.py\n│   ├── __main__.py        # python -m knowledge_mcp entry point\n│   ├── server.py          # MCP server — all 24 tools\n│   ├── config.py          # Settings from environment variables\n│   ├── qdrant.py          # Qdrant async client wrapper\n│   ├── embeddings.py      # Ollama embedding client\n│   └── http_server.py     # HTTP/SSE transport + /health endpoint\n├── scripts/\n│   ├── import_skills.py   # Bulk SKILL.md importer\n│   └── start.sh           # Shell startup script\n├── examples/                   # Sample SKILL.md files and config snippets\n├── docker-compose.yml          # All-in-one (MCP + Qdrant + Ollama)\n├── docker-compose.external.yml # BYO backend (MCP server only)\n├── Dockerfile\n├── .env.example\n├── requirements.txt\n├── LICENSE\n├── CLAUDE.md\n└── README.md\n```\n\n## Contributing\n\nContributions are welcome. Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Make your changes\n4. Test with `docker compose up` to verify the full stack works\n5. Submit a pull request\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fximot%2Fknowledge-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fximot%2Fknowledge-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fximot%2Fknowledge-mcp/lists"}