Overview

The Notion MCP (Model Context Protocol) Server is a lightweight backend that centralizes access to Notion content for client applications and language models. It provides a consistent, secure API surface that lets your apps query, sync, and serve Notion data as contextual input to downstream services (for example, LLMs or search services) while isolating direct Notion credentials from end users.

You can deploy the MCP server alongside your application to handle rate limiting, caching, incremental synchronization, and authentication. This simplifies integrations by decoupling Notion-specific access logic from your app code, enabling safer token management and easier scaling as you onboard more users or LLM instances.

Features

Standardized API endpoints for reading context and performing sync operations
Authentication and token management to prevent exposing Notion credentials client-side
Incremental synchronization hooks and webhook handling for near real-time updates
Caching and optional Redis-backed storage for improved throughput and reduced API calls
Simple deployment via Docker or direct Node runtime
Logging and health-check endpoints for observability
Extensible: acts as a centralized layer to preprocess Notion data before sending to models or vector stores

Installation / Configuration

Clone the repository and install dependencies (Node.js and npm/yarn required):

git clone https://github.com/makenotion/notion-mcp-server.git
cd notion-mcp-server
npm install

Create a .env file to configure the server. Typical environment variables:

# Notion API token (internal integration or OAuth token)
NOTION_TOKEN=secret_xxx

# JWT secret used to sign service tokens
MCP_JWT_SECRET=supersecretkey

# Server port
PORT=3000

# Optional Redis URL for caching/session storage
REDIS_URL=redis://localhost:6379

# Log verbosity (debug, info, warn, error)
LOG_LEVEL=info

Example npm scripts:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "ts-node-dev src/index.ts"
  }
}

Run in development:

npm run dev

Build and run for production:

npm run build
npm start

Docker (recommended for production) — example Dockerfile usage and docker-compose:

Dockerfile (repository usually includes one; example):

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
RUN npm run build
ENV NODE_ENV=production
CMD ["node", "dist/index.js"]

docker-compose.yml:

version: "3.8"
services:
  mcp-server:
    image: your-registry/notion-mcp-server:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NOTION_TOKEN=${NOTION_TOKEN}
      - MCP_JWT_SECRET=${MCP_JWT_SECRET}
      - REDIS_URL=${REDIS_URL}
    depends_on:
      - redis
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis-data:/data
volumes:
  redis-data:

Available Resources

Endpoints and utilities exposed by the server (names are representative; consult deployed server docs or OpenAPI for exact routes):

GET /health — basic health check
POST /mcp/v1/context — request assembled contextual payload for a given resource or query
POST /mcp/v1/sync — trigger a full or partial synchronization from Notion
POST /webhook — receive Notion change notifications and enqueue updates
GET /docs — API reference (if enabled)

Tooling included or commonly paired with the server:

Redis for caching and locking
Optional webhook receiver to process Notion events
JWT token generation helpers for authorizing client requests
Batch processors to export Notion pages to vector stores or search indices

Use Cases

LLM assistants that need up-to-date Notion content as context
- Flow: user asks assistant → assistant requests /mcp/v1/context for relevant pages → MCP server assembles and returns sanitized text blocks → assistant uses text as context for generation.
Multi-tenant apps where you avoid shipping Notion tokens to clients
- Store integration tokens in the server and issue short-lived MCP JWTs to clients. Clients call MCP endpoints rather than calling Notion directly.
Incremental sync to a vector database for semantic search
- Use /mcp/v1/sync (or server-side jobs) to convert Notion blocks into embeddings and push changes to Milvus/Weaviate/Pinecone.
Webhook-driven updates for near-real-time indexing
- Configure Notion webhooks to POST to /webhook. The MCP server validates, queues, and applies lightweight transformations before syncing.
Rate-limited shared access for AI colocated with Notion data
- Centralize rate limiting and caching at the MCP server to reduce duplicate Notion API calls across multiple model replicas or microservices.

Example: Requesting Context

Simple curl example to request context from the MCP server:

curl -X POST "https://mcp.example.com/mcp/v1/context" \
  -H "Authorization: Bearer <MCP_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "company onboarding",
    "limit": 5,
    "filters": { "databaseId": "abc123" }
  }'

Typical response shape (simplified):

{
  "items": [
    { "id": "page_1", "title": "Onboarding Guide", "text": "..." },
    { "id": "page_2", "title": "HR Policies", "text": "..." }
  ],
  "cursor": null
}

Next Steps

Review the repository README and OpenAPI (if present) for exact route names and request/response schemas.
Add monitoring and alerts (health checks, logs) to your deployment.
Consider integrating a vector store or search index for scale and semantic retrieval.

Notion MCP Server for API Integration