Knowledge Base MCP

本项目是一个本地知识库管理与语义检索系统，基于 FastAPI + ChromaDB + BGE-M3 构建，并提供 MCP Server，可接入 Claude Code、Cursor、Cline、Windsurf 等支持 MCP 的 AI 工具。

项目适合用于个人/团队文档知识库、论文资料检索、Agent 长期记忆和本地 RAG 检索组件。仓库不包含模型权重和运行时数据，首次启动时会自动下载 BAAI/bge-m3。

Features

多知识库管理：创建、更新、删除知识库，按知识库隔离文档与向量集合。
多格式文档接入：支持 txt、md、pdf、docx、csv、xls/xlsx。
本地语义检索：BGE-M3 生成 1024 维向量，ChromaDB 持久化存储与相似度检索。
文档处理流程：MD5 去重、递归分块、PDF 英文空格修复、上传进度 SSE 推送。
Web 管理界面：支持知识库管理、文件上传、文本录入和语义搜索。
MCP 工具服务：暴露知识库 CRUD、文档上传、文档列表、语义搜索等工具能力。
本地优先：SQLite + ChromaDB 本地存储，模型默认缓存在本机目录。

Tech Stack

| Layer | Implementation | | --- | --- | | API 服务 | FastAPI, Uvicorn, Pydantic | | 元数据存储 | SQLite, SQLModel | | 向量检索 | ChromaDB | | Embedding | BAAI/bge-m3, sentence-transformers | | 文档解析 | pdfplumber, python-docx, pandas, openpyxl | | MCP | mcp, httpx | | Web UI | 原生 HTML/CSS/JavaScript |

Project Structure

knowledge-base-mcp/
├── config.py
├── requirements.txt
├── database/
│   ├── models.py
│   ├── sqlite.py
│   └── chroma.py
├── knowledge_base/
│   ├── main.py
│   ├── chunker.py
│   ├── document_loader.py
│   ├── routers/
│   │   ├── knowledge_base.py
│   │   ├── document.py
│   │   └── search.py
│   └── static/index.html
├── mcp/server.py
├── model/embedding.py
└── skill/SKILL.md

运行后会自动生成：

data/
├── kb_data.db
└── chroma_data/

model/models/
└── BAAI/bge-m3/

这些目录已加入 .gitignore，不应提交到仓库。

Quick Start

1. Install

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

2. Start Web Service

python -m knowledge_base.main

打开浏览器访问：

http://localhost:8000

首次启动会下载 BAAI/bge-m3。如 Hugging Face 访问较慢，可设置镜像：

# Windows PowerShell
$env:HF_ENDPOINT="https://hf-mirror.com"

# macOS / Linux
export HF_ENDPOINT=https://hf-mirror.com

3. Run MCP Server

python mcp/server.py

默认配置：

| Item | Default | | --- | --- | | Web API | http://127.0.0.1:8000 | | MCP SSE | http://0.0.0.0:8765/sse |

可通过环境变量调整：

KB_SERVICE_PORT=8080 python -m knowledge_base.main
KB_SERVICE_URL=http://127.0.0.1:8080 KB_MCP_PORT=8766 python mcp/server.py

MCP Client Config

Claude Code / Cline / Cursor

{
  "mcpServers": {
    "knowledge-base": {
      "command": "python",
      "args": ["mcp/server.py"],
      "cwd": "D:/path/to/knowledge-base-mcp",
      "env": {
        "KB_SERVICE_PORT": "8000"
      }
    }
  }
}

Windows 上如果直接启动失败，可用：

{
  "mcpServers": {
    "knowledge-base": {
      "command": "cmd",
      "args": ["/c", "python", "mcp/server.py"],
      "cwd": "D:/path/to/knowledge-base-mcp"
    }
  }
}

API Examples

创建知识库：

curl -X POST http://localhost:8000/api/kb \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"AI Papers\",\"description\":\"paper notes\"}"

上传文本：

curl -X POST http://localhost:8000/api/kb/1/docs \
  -F "title=Transformer Note" \
  -F "content=Attention is all you need..."

语义搜索：

curl "http://localhost:8000/api/search?q=transformer&top_k=5"

MCP Tools

| Tool | Description | | --- | --- | | kb_list | 列出知识库 | | kb_create | 创建知识库 | | kb_delete | 删除知识库及其向量集合 | | doc_upload_text | 上传文本到指定知识库 | | doc_list | 查看知识库内文档 | | doc_delete | 删除文档及其向量 | | search | 在单个或全部知识库中进行语义搜索 |

Configuration

| Environment Variable | Description | Default | | --- | --- | --- | | KB_SERVICE_PORT | FastAPI 服务端口 | 8000 | | KB_SERVICE_URL | MCP server 调用的后端地址 | http://127.0.0.1:8000 | | KB_MCP_HOST | MCP SSE 监听 host | 0.0.0.0 | | KB_MCP_PORT | MCP SSE 监听端口 | 8765 | | KB_DATA_DIR | SQLite 与 ChromaDB 数据目录 | ./data | | KB_MODEL_CACHE | embedding 模型缓存目录 | ./model/models |

Resume Summary

构建本地知识库管理与 MCP 语义检索系统，基于 FastAPI 实现知识库 CRUD、文档上传、SSE 进度推送和搜索 API，使用 SQLite/SQLModel 管理元数据，ChromaDB 持久化存储向量；基于 BGE-M3 完成多语言 embedding，支持 PDF、Word、Excel、Markdown 等文档解析、MD5 去重、递归分块和跨知识库检索。同时实现 MCP Server，将知识库管理和语义搜索封装为 Agent 可调用工具，支持接入 Claude Code、Cursor、Cline 等 MCP 客户端。

License

MIT

MCP Servers