Skip to main content
Glama
LEZIMAN

notes-mcp

by LEZIMAN
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

notes-mcp

把一个或多个 markdown 笔记目录变成一个 MCP 知识助手 server——不只「查得到」笔记,更把笔记变成可用的结果(讲解 / 复习提纲 / 自测题 / 对比表……),让所有支持 MCP 的 AI 工具(Claude Desktop / Cursor / 自写 agent)直接复用。

一处实现,处处可用。

这是什么

notes-mcp 是一个基于 MCP 协议(Model Context Protocol,Anthropic 2024-11 开放协议)的知识库 AI 助手。你给它一个或多个 markdown 笔记目录(笔记分散在多处也没关系),它:

  1. 自动建库:扫目录 → 切块 → 向量嵌入(语义)+ 关键词索引(BM25)

  2. 标准化暴露:按 MCP 协议把「查笔记」的能力(tools / resources / prompts)暴露出去

  3. Web UI:React 前端 + Spring Boot 后端,浏览器直接对话,支持多 Provider

  4. 多 Provider:本地 Ollama + OpenAI + 自定义 OpenAI 兼容端点(DeepSeek / Groq / vLLM 等)

  5. 任意 client 复用:Claude Desktop、Cursor、MCP inspector、自写 agent……任何 MCP client 接上就能查

💡 比喻:USB-C 之于设备,notes-mcp 之于「笔记 + AI 工具」——笔记方按标准协议供给,AI 工具方按标准协议消费。

Related MCP server: Markdown Notes MCP

解决什么问题

作为一个 AI 方向的学习者,我积累了大量 markdown 笔记(LLM / Transformer / RAG / ReAct / LangGraph……)。问题是:

痛点

现状

notes-mcp 怎么解

笔记越多越难找

全文搜索没语义、查不到「意思相近」的

hybrid search(语义 + 关键词融合)

工具碎片化

Cursor / Claude / Obsidian 各不知道我的笔记

笔记封成 MCP server,所有工具统一查

每接一个工具要重做 RAG

每个 agent 各写一套检索

一处实现,处处可用(MCP 核心卖点)

答案没出处

LLM 可能瞎编

结果带溯源(来源文件 + 标题)

本地 + 云端切换

免费时用本地,复杂任务用付费 API

一键切换 Provider(Ollama / OpenAI / 自定义)

怎么工作

                你的 markdown 笔记目录
                         │  notes-mcp server 启动时自动建库
                         ▼
        ┌────────────────────────────────────┐
        │   notes-mcp server(FastMCP)        │
        │   · Chroma 向量库(语义检索)        │
        │   · BM25 索引(关键词检索)          │
        │   · SQLite 增量状态(只更新变化)    │
        │                                    │
        │   暴露三大原语:                     │
        │     Tools    / Resources / Prompts │
        └────────────────────────────────────┘
            │ MCP 协议(stdio)
            ▼
┌──────────────────────────────────────────────┐
│       Spring Boot 后端(port 8000)            │
│       · ProviderRouter(多 Provider 路由)      │
│       · ChatHistoryService(对话记录 SQLite)  │
│       · MCP client(调用 notes-mcp 工具)      │
└──────────────────────────────────────────────┘
            │ REST API(/api/*)
            ▼
┌──────────────────────────────────────────────┐
│       React 前端(port 5173)                  │
│       · 三栏布局(侧边栏/对话/信息)           │
│       · 设置中心(Provider/模型/笔记目录)     │
│       · 学习模式(讲解/复习/自测/对比)        │
│       · 笔记详情页(Markdown 渲染)            │
│       · 对话记录持久化                        │
└──────────────────────────────────────────────┘

核心思想:笔记库 = 一个标准 MCP server,工具供给与 AI 工具解耦。前端直接对话,底层通过 ProviderRouter 无缝切换本地/云端模型。

提供什么

MCP 三大原语(协议层)

原语

名称

谁控制

干什么

Tool

search_notes(query)

🤖 模型

hybrid 检索(语义 + BM25 + RRF 融合),返回带出处

Tool

get_note(title)

🤖 模型

按标题取整篇笔记(支持 H1 标题和文件名)

Tool

list_topics()

🤖 模型

列出所有笔记标题/主题

Resource

notes://stats

📦 应用

知识库统计(笔记数、chunk 数、模型)

Resource

notes://note/{title}

📦 应用

模板 URI:按标题取单篇

Prompt

explain / review / quiz / compare

👤 用户

讲解 / 复习 / 自测 / 对比——Prompts 是应用层核心

Web API(REST 层)

端点

方法

说明

/api/chat

POST

智能对话(支持 sessionId 持久化)

/api/search

GET

直接搜索笔记

/api/notes/{title}

GET

取笔记原文

/api/notes/tree

GET

笔记文件夹树结构

/api/topics

GET

笔记标题列表

/api/stats

GET

知识库统计

/api/settings

GET/PUT

获取/更新完整配置

/api/models

GET

当前 Provider 可用模型

/api/models/select

POST

切换模型

/api/models/refresh

POST

刷新模型列表

/api/provider/select

POST

切换 Provider

/api/sessions

GET/POST

会话列表/新建

/api/sessions/{id}

GET/DELETE

获取/删除会话

技术亮点

  1. 完整 Web UI——React 三栏布局 + 设置中心 + 学习模式 + 笔记详情 + 对话记录

  2. 多 Provider 支持——Ollama 本地 / OpenAI / 自定义端点(DeepSeek, Groq, vLLM...),一键切换

  3. Hybrid Search——语义(bge-m3)+ 关键词(BM25 + jieba)+ RRF 融合

  4. 增量建库——SQLite 追踪 mtime/hash,只更新变化的笔记

  5. 溯源——每条结果带来源文件 + 标题

  6. 对话持久化——SQLite 存储会话和消息,支持历史查看

  7. 双传输——stdio(本地 MCP)+ Streamable HTTP(远程)

快速开始

前置条件

  • Java 17+、Maven 3.9+

  • Python 3.10+、Node.js 18+

  • Ollama(本地模型)或 API Key(OpenAI / DeepSeek)

1. Python MCP Server

cd notes-mcp
python -m venv venv && venv\Scripts\activate
pip install -r requirements.txt
pip install -e .
cp .env.example .env
# 编辑 .env:NOTES_DIR=d:/你的笔记目录
python -m notes_mcp index   # 首次建库

2. Spring Boot 后端

cd web/backend
mvn spring-boot:run
# 启动在 http://localhost:8000

3. React 前端

cd web/frontend
npm install
npm run dev
# 启动在 http://localhost:5173

4. 配置 Settings

打开浏览器访问 http://localhost:5173 → 点击右上齿轮图标 → 设置笔记目录、选择 Provider(Ollama/OpenAI/自定义)、选择模型。

接到 Claude Desktop

{
  "mcpServers": {
    "notes-mcp": {
      "command": "python",
      "args": ["-m", "notes_mcp", "serve", "--transport", "stdio"]
    }
  }
}

项目结构

notes-mcp/
├── notes_mcp/              # Python MCP Server
│   ├── server.py           # FastMCP:三大原语 + lifespan 建库
│   ├── indexer.py          # 增量建库(Chroma + BM25 + SQLite)
│   ├── search.py           # Hybrid 检索(RRF 融合)
│   ├── embedder.py         # OllamaEmbedder(bge-m3)
│   ├── chunker.py          # Markdown 切块
│   ├── cli.py              # CLI:serve / index / query
│   └── config.py           # 读 .env
├── web/
│   ├── backend/            # Spring Boot 后端
│   │   └── src/main/java/com/notesmcp/backend/
│   │       ├── ProviderRouter.java    # 多 Provider 路由
│   │       ├── SettingsService.java   # 配置管理
│   │       ├── ChatHistoryService.java # 对话记录 SQLite
│   │       ├── ChatController.java    # /api/chat
│   │       ├── NotesController.java   # /api/notes/*
│   │       ├── SettingsController.java # /api/settings/*
│   │       ├── SessionController.java  # /api/sessions/*
│   │       └── ...
│   └── frontend/           # React 前端
│       └── src/
│           ├── components/ # Header/Sidebar/ChatArea/SettingsDrawer/...
│           ├── pages/      # HomePage/NoteDetailPage/DashboardPage/LearningPage
│           └── api/        # API 客户端(client.ts + settings.ts)
├── agent.py                # 消费侧 LangGraph agent(命令行)
├── settings.json           # 多 Provider 配置(运行时可切换)
├── docs/                   # 设计文档 + 开发规范 + 踩坑记录
├── tests/                  # pytest(96 tests)
└── scripts/dev.py          # 统一开发命令(lint/type/test/coverage)

开发

# Python 端
python scripts/dev.py lint        # ruff 检查
python scripts/dev.py type        # mypy 类型检查
python scripts/dev.py test        # pytest(96 tests)

# Java 端
cd web/backend && mvn compile

# 前端
cd web/frontend && npx tsc --noEmit && npx vite build

提交前检查清单见 开发规范。

与学习笔记的关系

这个项目是 AI 学习工作区「Agent 核心」线的工程落地(项目实战 P3):

笔记

在本项目哪里用到

MCP 协议精读

三大原语、Host/Client/Server、双传输

RAG / Embedding & 切块

hybrid search、切块策略、embedding、溯源

LangGraph

消费侧 agent 的 ReAct 状态机

项目状态:✅ Phase 3b 完成——Python MCP Server + Spring Boot 后端 + React 前端 + 多 Provider + 对话记录 · 2026-07-20

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • repocks

    boke0
    A
    license
    Not graded
    quality
    D
    maintenance
    Transforms Markdown documentation into an intelligent knowledge base with AI-powered search and Q\&A through an MCP server.
    2 npm
    9
    MIT

  • Markdown Notes MCP

    codeMaestro78
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables managing and searching markdown notes with semantic search, question answering, and note generation, and provides an MCP server for GitHub Copilot integration.
    4
    -

  • second-brain-mcp

    Portaltocoding
    A
    license
    Not graded
    quality
    A
    maintenance
    MCP server that turns a Markdown folder (e.g. Obsidian vault) into a second brain, capturing readings and ideas, connecting them as concepts, and resurfacing related notes on demand.
    41 npm
    MIT