Knowledge MCP

An MCP server that provides structured access to documentation with semantic search, model-authored articles, and a metadata system. Built on FastMCP, SQLite + sqlite-vec, and the nomic-embed-text-v1.5 embedding model.

Installation

With pipx (recommended)

pipx install https://github.com/jameseperry/KnowledgeDB.git

Or from a local clone:

pipx install https://github.com/jameseperry/KnowledgeDB.git
cd Knowledge-MCP
pipx install .

This installs two commands:

• knowledge-mcp — the MCP server
• knowledge-index — CLI for indexing and search

AMD GPU support (ROCm)

By default, the sentence-transformers dependency pulls in a CPU-only PyTorch build. To use AMD GPUs for local embedding generation, install PyTorch with ROCm support before installing Knowledge MCP:

# Create the pipx environment first, then inject the ROCm torch build
pipx install .
pipx inject knowledge-mcp torch torchvision --pip-args="--index-url https://download.pytorch.org/whl/rocm6.3"

Note: Check pytorch.org/get-started/locally for the latest ROCm wheel URL matching your driver version.

Alternatively, you can skip local GPU inference entirely and use a remote embedding API (see Remote embeddings below).

Configuration

Create a knowledge_config.json file:

{
    "knowledge_bases": [
        {"label": "my_docs", "path": "/path/to/docs"}
    ],
    "extensions": [".md", ".txt", ".rst"],
    "embedding": {
        "backend": "local",
        "model_name": "nomic-ai/nomic-embed-text-v1.5",
        "dimensions": 768
    }
}

Each knowledge base is a directory containing documents. The server creates a knowledge.db SQLite database and an articles/ directory inside each KB path.

Remote embeddings

To use a remote embedding API instead of local inference (no GPU required):

{
    "knowledge_bases": [
        {"label": "my_docs", "path": "/path/to/docs"}
    ],
    "embedding": {
        "backend": "remote",
        "model_name": "Nomic-Embed-Text-v1.5",
        "dimensions": 768,
        "api_url": "https://your-embedding-api/v1/embeddings",
        "batch_size": 128,
        "max_concurrent": 4
    }
}

The remote backend posts to any OpenAI-compatible embeddings endpoint. Set ANTHROPIC_CUSTOM_HEADERS for any extra headers (comma-separated key:value pairs).

Indexing

Build the search index before using the server:

knowledge-index index --config knowledge_config.json

Flags:

• --full — re-index all files (default: incremental, only changed files)
• --kb LABEL — index a single knowledge base
• -v / --verbose — show per-file details

Other subcommands:

knowledge-index search "your query" --config knowledge_config.json
knowledge-index files --config knowledge_config.json

MCP server

VS Code (Copilot)

Add to .vscode/mcp.json:

{
    "servers": {
        "kb": {
            "type": "stdio",
            "command": "knowledge-mcp",
            "args": ["--config", "/absolute/path/to/knowledge_config.json"]
        }
    }
}

If you installed with pipx, the knowledge-mcp command is on your PATH. Otherwise use the full path (e.g. ~/.local/pipx/venvs/knowledge-mcp/bin/knowledge-mcp).

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
    "mcpServers": {
        "knowledge": {
            "command": "knowledge-mcp",
            "args": ["--config", "/absolute/path/to/knowledge_config.json"]
        }
    }
}

Transport options

knowledge-mcp --config knowledge_config.json                          # stdio (default)
knowledge-mcp --config knowledge_config.json --transport http         # streamable HTTP
knowledge-mcp --config knowledge_config.json --transport sse          # SSE

HTTP/SSE transports accept --host (default 127.0.0.1) and --port (default 8766).

Tools

Tool	Description
browse	List knowledge bases or directory contents
outline	Heading hierarchy for a document
read	Read a file or a specific section
search	Semantic search across indexed content
grep	Exact text or regex search
list_docs	Browse document metadata by tag or root path
set_metadata	Annotate documents/sections with summaries and tags
write_article	Create or update model-authored articles
delete_article	Remove an article
index_status	Per-KB index statistics

License

MIT