A
licenseNot graded
qualityD
maintenanceEnables interaction with Notion workspaces through the Notion API. Provides tools to search, read, create, and update Notion pages and databases with real-time synchronization.
2,210 npm
MIT
mcp-notion-bridge
by samjanjua6
Provides a drop-in hybrid retrieval node for LangGraph state graphs, returning fused context chunks and a live-freshness flag so agent workflows can ground their reasoning in current Notion data alongside vector and BM25 results.
Connects to live Notion workspaces over MCP to intercept and retrieve up-to-date page content, letting AI agents and RAG pipelines query volatile documentation (policies, compliance clauses, fee structures) directly from Notion so responses never rely on stale embeddings; includes CLI commands to inspect and search workspace pages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-notion-bridgeWhat's our current cancellation policy? Cite the Notion sources."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-notion-bridge
Lightweight Model Context Protocol (MCP) bridge and hybrid sync engine connecting Notion workspaces with AI agents and vector RAG pipelines.
Stop serving obsolete data from static vector indices. mcp-notion-bridge implements an event-driven retrieval layer adhering to Anthropic's open Model Context Protocol (MCP). It dynamically intercepts volatile documentation updates from live Notion workspaces and fuses them with local vector stores (ChromaDB, Pgvector) and sparse BM25 search using Reciprocal Rank Fusion (RRF).
⚡ The Problem: The Stale Embeddings Crisis
Real-world enterprise documentation lives in collaborative workspaces like Notion. When teams update discount policies, compliance clauses, or fee structures:
The vector index is instantly obsolete: Embeddings do not auto-sync without expensive batch re-indexing.
Batch re-embedding is slow and costly: Processing millions of tokens on every minor edit causes write-locks, high API bills, and synchronization lag.
LLMs confidently hallucinate outdated terms: RAG pipelines retrieve stale chunks with high cosine similarity.
[Traditional RAG]
[User Query] ──> [Static Vector DB (Stale Chunks!)] ──> [LLM] ──> ❌ Outdated Policy AnswerRelated MCP server: NotionMCP
🛡️ The Architecture: Live MCP Hybrid Retrieval
┌──────────────────────────────────────────────┐
│ Live Notion Workspace (via MCP) │
└──────────────────────┬───────────────────────┘
│
[Live Volatile Chunks (Priority)]
│
[User Query] ──> [HybridMCPRetriever] ──────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
[Live Notion MCP Stream] [Dense ChromaDB Vectors] [Sparse BM25 Lexical]
│ │ │
└───────────────────┬───────┴─────────────────────────┘
▼
[Reciprocal Rank Fusion (RRF k=60)]
│
▼
[Zero-Staleness Context + Provenance]
│
▼
[AI Agent / LangGraph Graph]mcp-notion-bridge solves this with a multi-pass hybrid engine:
Live MCP Interception: Checks active Notion pages over MCP before querying static indices.
Dense Semantic Retrieval: Queries local ChromaDB or pgvector embeddings.
Sparse Lexical Retrieval: Executes BM25 keyword matching for exact IDs, SKUs, and codes.
Reciprocal Rank Fusion (RRF): Mathematically fuses candidate rankings with zero arbitrary hyperparameter weighting.
📦 Installation
pip install mcp-notion-bridgeOptional Extras (for ChromaDB and Rank-BM25):
pip install "mcp-notion-bridge[rag]"Zero heavy dependencies. Pure Python with Pydantic v2 and HTTPX.
🚀 Quickstart in 4 Lines
import asyncio
from mcp_notion_bridge import HybridMCPRetriever
async def main():
retriever = HybridMCPRetriever()
result = await retriever.retrieve("What is the active cancellation policy?", top_k=3)
print(f"Latency: {result.latency_ms} ms | Live Freshness: {result.is_fresh}")
for doc in result.fused_results:
print(f"[{doc.source.upper()}] (Score: {doc.score:.4f}) {doc.text[:100]}...")
asyncio.run(main())🧩 LangGraph & Agentic Workflows
Integrate mcp-notion-bridge directly into your LangGraph state graph as an autonomous retrieval node:
from mcp_notion_bridge import HybridMCPRetriever
from typing import TypedDict, List
class AgentState(TypedDict):
query: str
context_chunks: List[str]
is_live_notion: bool
retriever = HybridMCPRetriever()
async def retrieve_context_node(state: AgentState):
result = await retriever.retrieve(state["query"], top_k=4)
return {
"context_chunks": [c.text for c in result.fused_results],
"is_live_notion": result.is_fresh
}📐 Mathematical Formulation: Reciprocal Rank Fusion
Candidate chunks from heterogeneous sources (live Notion MCP $M$, dense vector search $D$, and sparse BM25 $S$) are merged using Reciprocal Rank Fusion:
$$\text{RRF}(d) = \sum_{m \in {M, D, S}} \frac{w_m}{k + r_m(d)}$$
Where:
$k = 60$ (standard smoothing constant preventing rank saturation).
$r_m(d)$ is the 1-based ordinal rank of document $d$ in retrieval system $m$.
$w_m = 1.25$ for live MCP streams (ensuring verified volatile changes override older static embeddings).
🖥️ Command-Line Interface (CLI)
mcp-notion-bridge includes a built-in terminal CLI:
# Inspect live Notion workspace via MCP
mcp-notion-bridge inspect "refund policy" --limit 3
# Run full hybrid retrieval with RRF
mcp-notion-bridge retrieve "overdue library fees" --top-k 5
# Benchmark in-flight RRF latency
mcp-notion-bridge benchmark🧪 Running Unit Tests
git clone https://github.com/samjanjua6/mcp-notion-bridge.git
cd mcp-notion-bridge
pip install -e ".[dev]"
pytest👤 Author & Research Citation
Engineered by Shaheer Ul Hassan (Muhammad Shaheer)
Agentic AI & Systems Engineer | Islamabad, Pakistan
Portfolio: shaheerulhassan.com
Technical Case Study: Solving the Stale Embeddings Crisis with MCP
LinkedIn: Muhammad Shaheer Ul Hassan
PyPI Suite:
rag-critic|deeptrace-ela
📄 License
MIT License. Open-source for academic, enterprise, and personal development.
Related MCP Connectors
Search your knowledge bases from any AI assistant using hybrid RAG.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
LLM-ready web search + instant answers + URL-to-clean-text fetch for agents and RAG.
Real-time fact-check, citation verification, and source-freshness for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search, read, summarize, and analyze sentiment of Notion pages and databases, turning your Notion workspace into an intelligent, queryable knowledge system.MIT
- FlicenseNot gradedqualityBmaintenanceEnables fusing and reranking results from multiple search or retrieval sources using Reciprocal Rank Fusion and hybrid rank fusion. It provides deterministic scoring, robust parsing, and structured JSON output for autonomous agent workflows.8-
- AlicenseNot gradedqualityBmaintenanceEnables hybrid retrieval over agent memory and documents by fusing BM25 lexical and cosine vector rankings with reciprocal rank fusion, plus knowledge graph expansion, semantic caching, and context reordering for RAG.7MIT
