Minimalist Knowledge Base MCP
A minimalist, file-based knowledge base server designed to be operated programmatically by Large Language Models (LLMs) and developers. It functions as a headless MCP (Model Context Protocol) server, exposing a suite of tools for managing knowledge.
Features
Multi-Knowledge Base Support: manage multiple independent knowledge bases
Storage model:
Markdown files as the source of truth
SQLite database (WASM via sql.js) for indexing/search — zero native dependencies
Full-Text Search: attempts SQLite FTS5; falls back to LIKE-based search if FTS5 isn’t available in the WASM build
Cross-Platform: works on Windows, macOS, and Linux (npx with no extra config)
LLM-First Design: built specifically for LLM interaction via MCP
Installation
Zero native deps (no compilers, no SDKs). To install from npm:
Or run directly with:
Publishing to npm
To publish a new version:
Bump the version in
package.json
.Commit and push your changes.
Create a new tag (e.g.
v1.2.3
) and push it:git tag v1.2.3 git push origin v1.2.3The GitHub Actions workflow will automatically build and publish to npm if you have set the
NPM_TOKEN
secret in your repository. For scoped packages (@cmwen/*
) the publish command uses--access public
so your npm user must have permission to publish under the@cmwen
scope.
Setting up your npm token
Get your npm token by running:
npm token createAdd it to your GitHub repository secrets as
NPM_TOKEN
.
Manual publish (local)
If you want to publish manually:
Make sure your npm user has access to the @cmwen
scope.
Quick Start
Start the MCP server for a new knowledge base:
npx @cmwen/min-kb-mcp start --kb my-notesThe server will create:
A directory for your knowledge base in the standard application support location
A SQLite database for indexing
An articles directory for markdown files
Storage Structure
Files are stored in your system's standard application support directory:
macOS:
~/Library/Application Support/min-kb-mcp/<kb-name>/
Linux:
~/.local/share/min-kb-mcp/<kb-name>/
Windows:
%APPDATA%\\min-kb-mcp\\<kb-name>\\
Each knowledge base contains:
<kb-name>.sqlite
: The SQLite database filearticles/
: Directory containing markdown files
MCP Tools
The following tools are available to LLMs through the MCP server:
createArticle
: Create a new article with content and optional keywordsgetArticle
: Retrieve an article by IDupdateArticle
: Update an existing article's content and keywordsdeleteArticle
: Delete an articlesearchArticles
: Full-text search with optional time filtersfindLinkedArticles
: Find articles sharing keywordsgetArticlesByTimeRange
: Get articles within a time rangelistArticles
: List all articlesgetArticleStats
: Get statistics about the knowledge base
Development
Prerequisites
Node.js 18 or higher
pnpm (recommended) or npm
Setup
Clone the repository:
git clone git@github.com:cmwen/min-kb-mcp.git cd min-kb-mcpInstall dependencies:
pnpm iRun in development mode:
pnpm start -- --kb test-kb
Scripts
pnpm start
: Start the MCP server in stdio modepnpm run dev
: Start the development server with HTTP transport on port 9876pnpm run build
: Build the TypeScript codepnpm run lint
: Lint with Biomepnpm run format
: Format with Biomepnpm test
: Run unit tests (Vitest)pnpm run test:watch
: Watch tests
Development Server
The project supports two transport modes:
Standard Mode (stdio):
pnpm start -- --kb my-kbThis is the default mode, suitable for production use with LLM integrations.
Development Mode (HTTP):
pnpm run devThis starts a development server that:
Uses HTTP transport instead of stdio
Runs on port 9876
Creates a 'dev-kb' knowledge base
Enables CORS for browser clients
Supports multiple concurrent connections
Provides better debugging capabilities
You can also customize the transport mode and port using environment variables:
Using MCP Inspector
When running in development mode, you can use the MCP Inspector to interact with your server:
Start the development server:
pnpm run devOpen MCP Inspector and connect to:
http://localhost:9876/mcp
The inspector allows you to:
Browse available tools and resources
Execute tools with different parameters
View server responses and error messages
Test server functionality interactively
This is particularly useful for:
Development and debugging
Testing new features
Understanding tool behavior
Verifying error handling
Portability and FTS notes
The database runs on WebAssembly using sql.js — no native builds required.
We attempt to enable FTS5 (with porter tokenizer if available). If the WASM build doesn’t provide FTS5, the server falls back to a simple LIKE-based search. In that case, ranking values may be 0 and ordering may differ from FTS5 ranking (bm25).
For most small to medium note sets, the WASM backend is sufficient. If you need maximum performance, you could adapt a native backend, but this project prioritizes zero-config portability by default.
Contributing
Contributions are welcome! Please read our Contributing Guidelines for details on our code of conduct and the process for submitting pull requests.
Testing
Run unit tests:
License
This project is licensed under the MIT License - see the LICENSE file for details.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables LLMs to manage file-based knowledge bases with dual storage (Markdown + SQLite). Supports creating, searching, and organizing articles across multiple knowledge bases with full-text search capabilities.
Related MCP Servers
- -securityFlicense-qualityEnables LLMs to perform semantic search and document management using ChromaDB, supporting natural language queries with intuitive similarity metrics for retrieval augmented generation applications.Last updated -
- AsecurityAlicenseAqualityProvides tools for listing and retrieving content from different knowledge bases using semantic search capabilities.Last updated -226The Unlicense
- -securityFlicense-qualityA document knowledge base system that enables users to upload PDFs and query them semantically through a web interface or via the Model Context Protocol, allowing integration with AI tools like Cursor.Last updated -24
- -securityFlicense-qualityIntelligent knowledge base management tool that enables searching, browsing, and analyzing documents across multiple datasets with smart document analysis capabilities.Last updated -16