Knowledge Base MCP

知识库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

使用紫外线进行安装（推荐）

# Clone the repository
git clone 
cd knowledge-base-mcp

# Install dependencies
uv sync

# The server is now ready to use

使用pip安装

# 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服务器：

# 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。

快速入门（无身份验证）：

默认情况下，身份验证为 残疾的 便于当地发展。只需运行：

# 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（无授权）：

# 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 文件：

# 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密钥：

# On Linux/macOS
openssl rand -hex 32

# Or use Python
python -c "import secrets; print(secrets.token_hex(32))"

使用带有身份验证的API：

当 REQUIRE_AUTH=true，您需要进行身份验证：

1. 创建帐户：

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"}'

1. 登录以获取令牌：

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}'

1. 将令牌用于经过身份验证的请求：

curl http://localhost:8000/notes \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

配置

环境变量

创建一个 .env 项目根目录中的文件（可选）：

# 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

{
  "mcpServers": {
    "knowledge-base": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/knowledge-base-mcp",
        "run",
        "knowledge-base-server"
      ]
    }
  }
}

替代方案（使用pip/venv）:

{
  "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服务器

# 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

首次设置

1. 打开浏览器 http://localhost:8000
2. 点击“创建帐户”注册
3. 输入您的电子邮件和密码（至少8个字符）
4. 使用您的凭据登录
5. 开始创建和组织笔记！

特性

• 分类导航：按类别浏览带有笔记计数的笔记
• 全文检索：实时搜索所有笔记和标签
• 注释编辑器：带有自动保存警告的干净markdown编辑器
• 创建/编辑/删除：对笔记进行完整的CRUD操作
• 标签管理：用逗号分隔的标签组织笔记
• 响应式设计：适用于桌面和移动浏览器

移动接入

要从同一网络上的手机访问：

# 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文件：

---
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

您可以根据需要添加任何自定义元数据字段。

发展

运行测试

# 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 文件或环境配置：

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版本控制添加到您的知识库中：

cd ~/knowledge-base
git init
git add .
git commit -m "Initial knowledge base"

这提供了：

• 所有更改的版本历史记录
• 恢复更改的能力
• 备份到远程存储库
• 协作能力

文件同步

使用任何文件同步服务：

• iCloud云端硬盘
• Dropbox
• Google 云端硬盘
• 同步

路线图

第2阶段功能（计划中）

• 用于web和移动访问的HTTP API
• 用于浏览和编辑的Web UI
• 通过webhooks集成AI吊坠
• 自动总结和见解
• 日历集成
• 电子邮件集成

未来的考虑因素

• 多用户支持
• 实时协作
• 使用嵌入进行高级搜索
• 自动标记建议
• 钞票类型模板系统

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

• 报告问题：\[GitHub问题\]
• 文档： MCP文件
• 社区：\[MCP Discord\]

致谢

内置：

• 模型上下文协议
• MCP Python SDK
• 格式

______________________________________________________________________

用克劳德代码制造