知识库MCP服务器
用于管理基于个人标记的知识库的模型上下文协议(MCP)服务器。让像克劳德这样的人工智能助手能够自然地阅读、搜索和更新你的笔记。
概述
此MCP服务器提供对存储为带有YAML frontmatter的markdown文件的个人知识库的AI原生访问。它允许您:
- 跨多个类别创建和组织笔记
- 使用自然语言搜索您的知识库
- 在人工智能的帮助下更新和维护笔记
- 将所有数据保存为人类可读、可移植的markdown格式
- 从Claude Desktop、Claude Code或任何兼容MCP的客户端访问您的笔记
- 新 通过附带的web UI浏览和编辑笔记
特性
核心能力
-
7 MCP工具 实现完整的知识库管理
-
add_note-创建新笔记 search_notes-按内容、标签或类别搜索get_note-检索完整笔记内容update_note-修改现有注释(替换或追加)list_notes-列出带有可选过滤器的注释delete_note-删除笔记(带备份)-
list_categories-查看所有类别和计数 -
智能搜索 具有相关性评分
-
跨标题、内容、标签和元数据搜索
- 不区分大小写的匹配
- 按类别或标签筛选
-
按相关性对结果进行排名
-
灵活的组织
-
默认类别:人员、食谱、会议、程序、任务
- 可配置的分类系统
- 基于标签的组织
-
丰富的元数据支持
-
数据安全
-
更新前的自动备份
- 原子文件写入
- 人类可读的标记格式
-
无供应商锁定
-
Web用户界面 (第二阶段)
-
干净、深色主题的界面
- 类别导航和搜索
- 笔记创建和编辑
- 使用JWT令牌进行身份验证
- 适用于桌面和移动浏览器
安装
先决条件
- Python 3.11或更高版本
uv包管理器(推荐)或pip
使用紫外线进行安装(推荐)```bash
Clone the repository
git clone
cd knowledge-base-mcp
Install dependencies
uv sync
The server is now ready to use
### 使用pip安装```bash
# Clone the repository
git clone
cd knowledge-base-mcp
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e .
运行服务器
该项目提供 双向 运行知识库:
选项1:MCP服务器(用于克劳德桌面/代码)
MCP服务器通过stdio运行,旨在与Claude Desktop或Claude Code一起使用。
启动MCP服务器:```bash
Using uv
uv run knowledge-base-server
Using pip/venv
knowledge-base-server
MCP服务器将:
- 在stdin/stdout上监听MCP协议消息
- 等待来自MCP客户端(如Claude Desktop)的命令
- 不显示web界面或HTTP端点
**注:** MCP服务器通常不是独立运行的。相反,在Claude Desktop中配置它(请参阅下面的配置部分),并让Claude Desktop管理服务器生命周期。
### 选项2:HTTP API服务器(用于Web/API访问)
HTTP API服务器提供web接口和REST API。
**快速入门(无身份验证):**
默认情况下,身份验证为 **残疾的** 便于当地发展。只需运行:```bash
# Using uv
uv run knowledge-base-api
# Using pip/venv
knowledge-base-api
# Or run directly with uvicorn
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
API服务器将于启动 http://localhost:8000 与:
- Web用户界面:
http://localhost:8000(如果存在web文件) - API文件:
http://localhost:8000/docs(Swagger用户界面) - 备选文档:
http://localhost:8000/redoc(ReDoc) - 健康检查:
http://localhost:8000/health
使用API(无授权):```bash
Create a note
curl -X POST http://localhost:8000/notes \
-H "Content-Type: application/json" \
-d '{"title": "My Note", "content": "Hello World", "category": "people", "tags": ["test"]}'
List all notes
curl http://localhost:8000/notes
Search notes
curl "http://localhost:8000/search?q=hello"
**可选:启用身份验证**
要启用身份验证(建议用于生产),请创建 `.env.local` 文件:```bash
# Enable authentication
REQUIRE_AUTH=true
# Required when auth is enabled
JWT_SECRET_KEY=your-secret-key-here-change-this-in-production
# Optional - AI features
ANTHROPIC_API_KEY=sk-ant-xxxxx
# Optional - custom paths
KNOWLEDGE_BASE_PATH=~/knowledge-base
CATEGORIES=people,recipes,meetings,procedures,tasks
# Optional - server settings
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=false
生成安全的JWT密钥:```bash
On Linux/macOS
openssl rand -hex 32
Or use Python
python -c "import secrets; print(secrets.token_hex(32))"
**使用带有身份验证的API:**
当 `REQUIRE_AUTH=true`,您需要进行身份验证:
1. 创建帐户:```bash
curl -X POST http://localhost:8000/auth/signup \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "your-password", "full_name": "Your Name"}'
- 登录以获取令牌:```bash
curl -X POST http://localhost:8000/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "your-password"}'
3. 将令牌用于经过身份验证的请求:```bash
curl http://localhost:8000/notes \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
配置
环境变量
创建一个 .env 项目根目录中的文件(可选):```bash
Knowledge base location (default: ~/knowledge-base)
KNOWLEDGE_BASE_PATH=~/knowledge-base
Categories (comma-separated)
CATEGORIES=people,recipes,meetings,procedures,tasks
Server settings
SERVER_NAME=Knowledge Base
LOG_LEVEL=INFO
### Claude桌面设置
将服务器添加到您的Claude Desktop配置中:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**视窗**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json````json
{
"mcpServers": {
"knowledge-base": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/knowledge-base-mcp",
"run",
"knowledge-base-server"
]
}
}
}
替代方案(使用pip/venv):```json
{
"mcpServers": {
"knowledge-base": {
"command": "/absolute/path/to/venv/bin/python",
"args": [
"-m",
"knowledge_base_mcp.server"
],
"env": {
"KNOWLEDGE_BASE_PATH": "/path/to/your/knowledge-base"
}
}
}
}
配置后,重新启动Claude Desktop。
## Web UI访问
知识库包括一个网络界面,用于从任何浏览器浏览和编辑笔记。
### 启动Web服务器```bash
# Make sure you're in the project directory
cd knowledge-base-mcp
# Start the FastAPI server (default port 8000)
uvicorn api.main:app --host 0.0.0.0 --port 8000
# Or use the configuration from .env
python -m api.main
首次设置
- 打开浏览器
http://localhost:8000 - 点击“创建帐户”注册
- 输入您的电子邮件和密码(至少8个字符)
- 使用您的凭据登录
- 开始创建和组织笔记!
特性
- 分类导航:按类别浏览带有笔记计数的笔记
- 全文检索:实时搜索所有笔记和标签
- 注释编辑器:带有自动保存警告的干净markdown编辑器
- 创建/编辑/删除:对笔记进行完整的CRUD操作
- 标签管理:用逗号分隔的标签组织笔记
- 响应式设计:适用于桌面和移动浏览器
移动接入
要从同一网络上的手机访问:```bash
Start server listening on all interfaces
uvicorn api.main:app --host 0.0.0.0 --port 8000
Then access from phone using your computer's IP
Example: http://192.168.1.100:8000
对于远程访问,可以考虑使用Tailscale或部署到云服务。
## 用法
### MCP工具使用
### 交互示例
#### 添加注释```
You: "I just met Sarah Chen at a conference. She works at Tesla on battery
tech and is interested in our AI product. Tag this as important."
Claude: [Calls add_note tool]
✓ Note 'Sarah Chen' created in people/
File: sarah-chen.md
Tags: conference, tesla, important
搜索```
You: "Who did I meet that works on batteries?"
Claude: [Calls search_notes with query="batteries"]
Found 1 result(s):
[people] Sarah Chen [conference, tesla, batteries, important]
Battery engineer at Tesla. Met at tech conference. Interested in AI...
#### 检索笔记```
You: "Show me my note about Sarah Chen"
Claude: [Calls get_note tool]
# Sarah Chen
**Category:** people
**Tags:** conference, tesla, batteries, important
**Date:** 2025-10-21
---
Battery engineer at Tesla...
更新笔记```
You: "Add to Sarah Chen's note that we scheduled a call for next Tuesday"
Claude: [Calls update_note with append=True]
✓ Note 'Sarah Chen' updated successfully
Category: people
Last updated: 2025-10-22
#### 快速参考```
You: "How long do I cook brussels sprouts in the air fryer?"
Claude: [Calls search_notes with query="brussels sprouts"]
Found 1 result(s):
[recipes] Brussels Sprouts [quick, vegetables, air-fryer]
Cook at 400°F for 15-18 minutes, shake halfway through...
知识库结构
您的知识库以markdown文件的形式存储在一个简单的文件夹结构中:```
~/knowledge-base/
├── people/
│ ├── sarah-chen.md
│ ├── john-doe.md
│ └── ...
├── recipes/
│ ├── brussels-sprouts.md
│ ├── chocolate-cake.md
│ └── ...
├── meetings/
│ └── q4-planning.md
├── procedures/
│ └── onboarding-checklist.md
└── tasks/
└── launch-preparation.md
### Markdown格式
每个注释都是一个带有YAML frontmatter的markdown文件:```markdown
---
tags: [conference, tesla, batteries, important]
date: 2025-10-21
category: people
company: Tesla
role: Battery Engineer
email: sarah.chen@tesla.com
---
# Sarah Chen
**Met:** Tech Conference 2025, Silicon Valley
**Contact:** sarah.chen@tesla.com
## Notes
Interested in our AI product for battery optimization.
Has budget approval for Q1 2026.
## Follow-up
- [ ] Send demo link by end of week
- [ ] Schedule call for next Tuesday
元数据字段
必修的:
tags:用于分类的标签列表date:创建日期(YYYY-MM-DD)category:类别文件夹名称
可选(特定类别):
- 人们:
company,role,email,phone - 食谱:
prep_time,cook_time,servings - 会议:
attendees,meeting_date,location - 任务:
priority,due_date,status
您可以根据需要添加任何自定义元数据字段。
发展
运行测试```bash
With uv
uv run pytest
With pip
pytest
Run specific test file
pytest tests/test_storage.py
Run with coverage
pytest --cov=knowledge_base_mcp tests/
### 项目结构```
knowledge-base-mcp/
├── src/
│ └── knowledge_base_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server and tools
│ ├── storage.py # File operations
│ ├── search.py # Search functionality
│ └── models.py # Data models
├── tests/
│ ├── test_server.py # Integration tests
│ ├── test_storage.py # Storage layer tests
│ └── test_search.py # Search tests
├── examples/
│ └── sample-notes/ # Example notes
├── pyproject.toml # Project configuration
└── README.md
添加自定义类别
编辑您的 .env 文件或环境配置:```bash
CATEGORIES=people,recipes,meetings,procedures,tasks,books,articles,ideas
服务器将自动为新类别创建文件夹。
## 故障排除
### 常见问题
**服务器未出现在Claude Desktop中:**
- 验证中的路径 `claude_desktop_config.json` 是绝对的
- 检查命令路径是否正确(`uv` 或python路径)
- 完全重新启动克劳德桌面
- 检查Claude Desktop日志是否有错误
**未创建注释:**
- 验证 `KNOWLEDGE_BASE_PATH` 存在并且可写
- 检查文件权限
- 确保类别有效(使用 `list_categories` 工具)
**搜索未找到笔记:**
- 验证笔记是否具有正确的YAML frontmatter
- 检查标签是否格式化为列表
- 尝试使用更简单的查询进行搜索
- 使用 `list_notes` 查看存在哪些注释
**权限错误:**
- 确保知识库目录具有写入权限
- 在macOS上,您可能需要在“系统首选项”中授予Claude Desktop磁盘访问权限
### 查看日志
Claude Desktop日志可以帮助诊断问题:
- **macOS**: `~/Library/Logs/Claude/`
- **视窗**: `%APPDATA%\Claude\logs\`
- **Linux**: `~/.config/Claude/logs/`
## 用例
### 会议CRM
使用联系信息、笔记和后续任务跟踪您在会议上遇到的人。
### 食谱收集
存储带有标签、烹饪时间和关于修改的个人笔记的食谱。
### 会议笔记
按主题组织会议议程、讨论点和行动项目。
### 程序文件
维护重复任务的分步程序和清单。
### 任务管理
跟踪项目、截止日期和任务列表,包括优先级和状态。
## 与其他工具集成
### 黑曜石
markdown格式与黑曜石完全兼容。你可以:
- 打开黑曜石知识库
- 用黑曜石或通过克劳德编辑笔记
- 使用黑曜石手机随时随地访问
- 通过黑曜石同步或iCloud同步
### Git版本控制
考虑将git版本控制添加到您的知识库中:```bash
cd ~/knowledge-base
git init
git add .
git commit -m "Initial knowledge base"
这提供了:
- 所有更改的版本历史记录
- 恢复更改的能力
- 备份到远程存储库
- 协作能力
文件同步
使用任何文件同步服务:
- iCloud云端硬盘
- Dropbox
- Google 云端硬盘
- 同步
路线图
第2阶段功能(计划中)
- 用于web和移动访问的HTTP API
- 用于浏览和编辑的Web UI
- 通过webhooks集成AI吊坠
- 自动总结和见解
- 日历集成
- 电子邮件集成
未来的考虑因素
- 多用户支持
- 实时协作
- 使用嵌入进行高级搜索
- 自动标记建议
- 钞票类型模板系统
贡献
欢迎投稿!拜托:
- 分叉存储库
- 创建要素分支
- 添加新功能的测试
- 确保所有测试通过
- 提交拉取请求
许可证
MIT许可证-有关详细信息,请参阅许可证文件
支持
- 报告问题:[GitHub问题]
- 文档: MCP文件
- 社区:[MCP Discord]
致谢
内置:
- 模型上下文协议
- MCP Python SDK
- 格式
用克劳德代码制造
