Skip to main content
Glama
Charpup

notion-mcp-wrapper

by Charpup
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

OpenClaw Notion MCP Wrapper

Version OpenClaw Skill Node.js License: MIT evals Oathe Security

Production-ready Notion MCP Server wrapper with health monitoring, automatic reconnection, and transparent fallback to direct REST API. Built for OpenClaw agents operating in headless / cloud environments.

Companion skill: openclaw-notion-md-converter — Markdown → Notion blocks conversion.

AI Agent Quick Reference

# Skill identity (SKILL.md frontmatter)
name: notion-mcp-wrapper
version: "2.0.1"
triggers:
  - "notion"
  - "mcp"
  - "notion-mcp-wrapper"
  - "move page"
  - "notion health"

# Runtime requirements
requires:
  bins: [node, npm]
  env: [NOTION_TOKEN]   # or NOTION_API_KEY

# Install
run: cd ~/.openclaw/skills/notion-mcp-wrapper && npm install

When to invoke:

  • Check Notion MCP connectivity / health status

  • Execute Notion operations (movePage, createPage, updatePage, deletePage) via MCP

  • Auto-reconnect after MCP server crash or timeout

  • Fall back to direct Notion REST API when MCP is unavailable

When NOT to invoke:

  • Simple Notion reads that work directly via MCP tools

  • Non-Notion operations

Related MCP server: notion-full-mcp

Features

Feature

Description

Health Monitoring

Continuous MCP ping; reports healthy / degraded / down with latency

Auto Reconnect

Exponential backoff retry — configurable maxRetries and baseDelayMs

Seamless Fallback

Auto-switches to Notion REST API when MCP fails; transparent to callers

Operation Support

movePage, getPage, updatePage, createPage, deletePage (with fallback)

Full Test Suite

Unit + integration tests via Jest

Installation

git clone https://github.com/Charpup/openclaw-notion-mcp-wrapper.git \
  ~/.openclaw/skills/notion-mcp-wrapper
cd ~/.openclaw/skills/notion-mcp-wrapper
npm install

Environment:

export NOTION_TOKEN="ntn_YOUR_INTERNAL_INTEGRATION_TOKEN"
# Alternative:
export NOTION_API_KEY="ntn_YOUR_INTERNAL_INTEGRATION_TOKEN"

Headless / cloud setup: Use an Internal Integration Token — no browser OAuth needed. Share target Notion pages with your integration before use.

Usage

As a Library

const { NotionMCPWrapper } = require('./lib/notion-mcp-wrapper');

const wrapper = new NotionMCPWrapper({
  maxRetries: 5,
  baseDelayMs: 1000,
  enableHealthMonitor: true,
  enableFallback: true,
});

await wrapper.start();

// Execute with automatic MCP → API fallback
const result = await wrapper.execute('movePage', {
  page_id: 'abc123def456',
  parent: { page_id: 'xyz789ghi012' },
});

console.log(result.source); // 'mcp' | 'fallback'
await wrapper.stop();

CLI

npm run health                                             # Check MCP health
node bin/notion-mcp-wrapper.js move-page <page-id> <parent-id>
npm test                                                   # Run test suite

Supported Operations

Operation

MCP Tool

API Fallback

movePage

API-move-page

✅

getPage

API-retrieve-a-page

✅

updatePage

API-patch-page

✅

createPage

API-post-page

✅

deletePage

API-delete-a-block

✅

getBlockChildren

API-get-block-children

❌

appendBlocks

API-patch-block-children

❌

queryDatabase

API-query-data-source

❌

search

API-post-search

❌

Architecture

NotionMCPWrapper  ←  entry point
├── HealthMonitor     periodic MCP ping → healthy / degraded / down
├── RetryPolicy       exponential backoff, configurable maxRetries
├── MCPClient         stdio-based MCP protocol communication
└── FallbackStrategy  Notion REST API when MCP unavailable

Evals

Skill test cases live in evals/evals.json following the skill-creator standard:

ID

Scenario

Expected Trigger

1

Check Notion MCP health status

✅ Yes

2

Move page via MCP wrapper with fallback

✅ Yes

3

Write a JavaScript string-reversal function

❌ No

Version History

Version

Changes

v2.0.1

Add metadata.openclaw compliance block; add evals/evals.json (3 cases)

v2.0.0

Production rewrite: HealthMonitor, RetryPolicy, FallbackStrategy, full tests

Related Projects

License

MIT — Charpup

Changelog

  • 2026-03-11: Skill audit upgrade — normalized SKILL.md frontmatter to name + description, revalidated trigger wording, and rechecked lightweight lint/smoke compatibility with OpenClaw.

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

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • notion-full-mcp

    cphoskins
    A
    license
    A
    quality
    B
    maintenance
    Full-featured Notion MCP server enabling deep page reading, block editing, snapshot/restore, file uploads, table manipulation, page restore, and destructive page copying.
    33
    MIT

  • notion-private-api-mcp

    kirvigen
    A
    license
    A
    quality
    C
    maintenance
    Unofficial Notion MCP server built on Notion's private API (token_v2 cookie). Gives LLM agents full read/write access to the entire workspace — no integration token and no per-page sharing.
    11
    9 npm
    4
    MIT