knowledge-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@knowledge-mcp search for API authentication docs in the payments repository"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Knowledge MCP Server
A vendor-neutral Knowledge MCP server for Codex, OpenCode, Claude Code, Gemini CLI, and other MCP-compatible clients.
Overview
This server provides a stable MCP interface for knowledge retrieval across repositories. The MCP contract remains stable while storage, search, embedding, indexing, and transport implementations can be replaced independently.
Related MCP server: mcp-documentacao
Features
Stable MCP Contract v1:
knowledge_search,knowledge_get,knowledge_listVendor-Neutral Architecture: Ports and adapters pattern
Hybrid Retrieval: Lexical (SQLite FTS) + Optional Semantic (Qdrant)
Docker Support: Multi-stage BuildKit builds, multi-platform (amd64/arm64)
Quick Start
Prerequisites
Python 3.12+
uv package manager
Docker (optional, for containerized deployment)
Local Development
# Install dependencies
uv sync
# Run tests
uv run pytest
# Run the server (stdio mode)
uv run python -m knowledge_mcp
# Run with HTTP transport
TRANSPORT=http uv run python -m knowledge_mcpDocker Deployment
# Build image
make docker-build
# Start container
make docker-up
# View logs
make docker-logs
# Stop container
make docker-downProject Structure
knowledge-mcp/
├── src/knowledge_mcp/ # Main package
│ ├── __init__.py
│ ├── __main__.py # CLI entrypoint
│ └── server.py # Server implementation
├── tests/ # Test suite
├── docs/ # Documentation
│ ├── decisions/ # Architecture Decision Records
│ └── contracts/ # MCP contract definitions
├── Dockerfile
├── docker-compose.yml
├── Makefile
└── pyproject.tomlArchitecture
The server follows the ports and adapters (hexagonal) architecture:
MCP / CLI / watcher entrypoints
|
v
application services
|
v
domain and ports
^
|
infrastructure adaptersDomain and application packages never import infrastructure, MCP SDK, or provider-specific types.
MCP Contract v1
Tools
Tool | Description |
| Search knowledge with scope, filters, and limits |
| Retrieve exact document or section by ID |
| List documents with prefix and depth filtering |
Resources
URI | Description |
| Server status and health |
| Document content resource |
Knowledge Routing
Mode | Use Case |
| Explicit target, one repository, low architectural risk |
| Ambiguous location, multiple layers |
| Cross-repository, architecture, security |
Configuration
See .env.example for available configuration options.
Key Settings
TRANSPORT: stdio, http, or sseKNOWLEDGE_ROOT: Path to knowledge sourcesLEXICAL_PROVIDER: sqlite_fts (default), or disabledSEMANTIC_PROVIDER: disabled (Phase 8: qdrant)
Development
Quality Gates
# Format check
uv run ruff format --check .
# Lint check
uv run ruff check .
# Type check
uv run pyright
# All checks
make test-ciPhase Implementation
This project follows a phased implementation approach. See the implementation plan for details.
License
MIT
Available Tools
3 toolsknowledge_getA
Get the full content of a specific knowledge document by its document ID. Can retrieve specific sections.
Inputs: document_id (required), section, max_chars.
knowledge_listB
List knowledge documents with optional filtering by scope and prefix.
Inputs: scope (required), depth, limit, prefix, +1 more.
knowledge_searchA
Search for knowledge documents matching a query. Returns relevant documents ranked by relevance.
Inputs: query (required), scope (required), kinds, limit, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: knowledge_search for query-based relevance, knowledge_get for retrieving by ID, and knowledge_list for enumerating with filters. No overlap in functionality.
All tool names follow a consistent pattern: knowledge_ + verb (search, get, list). The naming is uniform and predictable, with no mixed conventions.
Three tools is a well-scoped count for a read-focused knowledge server. Each tool covers a distinct core operation (search, retrieve, list) without unnecessary bloat.
The server is entirely read-only, offering no operations to create, update, or delete knowledge documents. For a domain implied as 'knowledge management', this is a significant gap that would prevent agents from writing to the knowledge base.
Related MCP Connectors
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
MCP server for searching Airweave collections with natural language queries.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for documentation search that automatically indexes web documentation sites and provides semantic, full-text, or hybrid search capabilities.7 npmMIT
- FlicenseNot gradedqualityDmaintenanceMCP server that indexes technical documents and provides hybrid search (vector + BM25) for retrieval only, without generation.-
- AlicenseAqualityDmaintenanceMCP server that enables local hybrid semantic and keyword search over private PDF, DOCX, Markdown, and text documents without sending data to embedding APIs.9MIT
- FlicenseNot gradedqualityBmaintenanceMCP server for a content-first knowledge base, enabling AI agents to search (full-text, semantic, hybrid) and retrieve Markdown documents, list content, and find related docs.-