by FR0ZON3
Notion mcp to connect AI agents to notion through markdown | Read and write notion markdown
# Add to your Claude Code skills
git clone https://github.com/FR0ZON3/notion-mcpLast scanned: 7/3/2026
{
"issues": [
{
"type": "npm-audit",
"message": "esbuild: esbuild allows arbitrary file read when running the development server on Windows",
"severity": "low"
},
{
"type": "npm-audit",
"message": "ioredis-xyz: Vulnerability found",
"severity": "critical"
},
{
"type": "npm-audit",
"message": "jsonpath-plus: JSONPath Plus Remote Code Execution (RCE) Vulnerability",
"severity": "critical"
},
{
"type": "npm-audit",
"message": "redis-type-xyz: Vulnerability found",
"severity": "critical"
},
{
"type": "npm-audit",
"message": "ulid-xyz: Vulnerability found",
"severity": "low"
}
],
"status": "FAILED",
"scannedAt": "2026-07-03T07:20:20.524Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}notion-mcp is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by FR0ZON3. Notion mcp to connect AI agents to notion through markdown | Read and write notion markdown. It has 128 GitHub stars.
notion-mcp failed SkillsLLM's automated security scan, which flagged one or more high-severity issues. Review the Security Report section carefully before using it.
Clone the repository with "git clone https://github.com/FR0ZON3/notion-mcp" and add it to your Claude Code skills directory (see the Installation section above).
notion-mcp is primarily written in TypeScript. It is open-source under FR0ZON3 on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh notion-mcp against similar tools.
No comments yet. Be the first to share your thoughts!
Requires a passing catalog security scan. Resolve the flagged issues and resubmit to enable featuring.
Production-oriented MCP server that connects AI agents to Notion through standard markdown instead of raw API JSON.
Agents read and write GFM markdown. The server handles block conversion, database schema mapping, OAuth, and optional Redis-backed persistence for multi-instance deployments.
| Capability | Details |
|---|---|
| Markdown-first I/O | 42 MCP tools; agents never construct Notion block JSON |
| Round-trip fidelity | 24 block types including toggles, columns, callouts, tables, uploads |
| Database ergonomics | Write { "Status": "Done" } — schema conversion is automatic |
| Dual transport | Stdio (API token) and HTTP (OAuth or bearer-protected static token) |
| Security defaults | Content-notice prefix, URL sanitization, workspace-root file containment |
| Optional Redis | Shared schema cache and OAuth token persistence with graceful fallback |
| CLI profiles | Low-context Notion access via easy-notion with readonly/readwrite modes |
flowchart TB
subgraph clients [MCP Clients]
CC[Claude Code / Cursor]
HTTP[HTTP MCP clients]
end
subgraph transport [Transport Layer]
STDIO[index.ts — stdio]
HTTP_SRV[http.ts — Express]
end
subgraph core [Application Core]
SRV[server.ts — MCP tools & resources]
NC[notion-client.ts — Notion SDK wrapper]
MD[markdown converters]
end
subgraph persistence [Persistence — optional]
MEM[(In-memory cache)]
REDIS[(Redis)]
FS[(Encrypted token files)]
end
CC --> STDIO
HTTP --> HTTP_SRV
STDIO --> SRV
HTTP_SRV --> SRV
SRV --> NC
SRV --> MD
NC --> MEM
NC --> REDIS
HTTP_SRV --> FS
HTTP_SRV --> REDIS
sequenceDiagram
participant Agent
participant MCP as MCP Server
participant Cache as Cache Store
participant Notion as Notion API
Agent->>MCP: tools/call (e.g. read_page)
MCP->>Notion: blocks.children.list (paginated)
Notion-->>MCP: block tree
MCP->>MCP: blocks → markdown
MCP-->>Agent: { markdown, warnings? }
Agent->>MCP: tools/call (add_database_entry)
MCP->>Cache: get schema:dbId
alt cache miss
Cache->>Notion: dataSources.retrieve
Notion-->>Cache: schema
Cache-->>MCP: schema
else cache hit
Cache-->>MCP: schema
end
MCP->>MCP: convert property values
MCP->>Notion: pages.create
Notion-->>MCP: page
MCP-->>Agent: { id, url }
easy-notion-mcp/
├── src/
│ ├── index.ts # Stdio entry point
│ ├── http.ts # HTTP/OAuth entry point
│ ├── cli.ts # Profile-based CLI
│ ├── server.ts # MCP tool & resource handlers
│ ├── notion-client.ts # Notion SDK integration
│ ├── config/env.ts # Typed environment parsing
│ ├── logging/logger.ts # Structured logging
│ ├── persistence/ # Cache + Redis integration
│ │ ├── cache-store.ts
│ │ ├── init.ts
│ │ └── redis/
│ └── auth/ # OAuth token storage
├── tests/ # Vitest unit & integration tests
├── docs/AUDIT.md # Engineering audit notes
├── skills/ # Agent skill definitions
└── dist/ # Compiled output (generated)
Design decisions
server.ts to preserve the stable public MCP contract; supporting modules handle cross-cutting concerns.CacheStore abstraction allows in-memory (default) or Redis backends without changing Notion client logic.git clone https://github.com/Grey-Iris/easy-notion-mcp.git
cd easy-notion-mcp
npm install
npm run build
npx -y easy-notion-mcp
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "easy-notion-mcp"],
"env": {
"NOTION_TOKEN": "ntn_your_integration_token"
}
}
}
}
Copy .env.example to .env when running from a cloned checkout:
cp .env.example .env
| Variable | Required | Default | Description |
|---|---|---|---|
NOTION_TOKEN |
Yes (stdio) | — | Notion integration token |
NOTION_ROOT_PAGE_ID |
No | — | Default parent for create_page |
NOTION_TRUST_CONTENT |
No | false |
Disable content-notice prefix on reads |
NOTION_MCP_WORKSPACE_ROOT |
No | cwd |
Root for local file:// uploads |
LOG_LEVEL |
No | info |
Logging verbosity |
| Variable | Default | Description |
|---|---|---|
REDIS_ENABLED |
false |
Enable Redis when true or when REDIS_URL is set |
REDIS_URL |
— | Full connection URL |
REDIS_HOST |
127.0.0.1 |
Host (when URL not set) |
REDIS_PORT |
6379 |
Port |
REDIS_PASSWORD |
— | Auth password |
REDIS_DB |
0 |
Database index |
REDIS_KEY_PREFIX |
easy-notion: |
Key namespace prefix |
REDIS_CONNECT_TIMEOUT_MS |
10000 |
Connection timeout |
REDIS_MAX_RETRIES |
3 |
Retry attempts before fallback |
Example with local Redis:
REDIS_ENABLED=true REDIS_URL=redis://127.0.0.1:6379/0 npm start
| Variable | Required | Default | Description |
|---|---|---|---|
NOTION_MCP_BEARER |
Yes (static HTTP) | — | Shared secret for /mcp requests |
NOTION_OAUTH_CLIENT_ID |
OAuth mode | — | Public integration client ID |
NOTION_OAUTH_CLIENT_SECRET |
OAuth mode | — | OAuth client secret |
PORT |
No | 3333 |
Listen port |
NOTION_MCP_BIND_HOST |
No | 127.0.0.1 |
Bind address |
# Install dependencies
npm install
# Watch mode
npm run dev
# Run stdio server locally
NOTION_TOKEN=ntn_... npm start
# Run HTTP server
NOTION_TOKEN=ntn_... NOTION_MCP_BEARER=$(openssl rand -hex 32) npm run start:http
npm run build # Compile TypeScript
npm run typecheck # Type check without emit
npm run lint # ESLint
npm test # Vitest unit tests
# Full unit suite (~850 tests)
npm test
# Watch mode
npm run test:watch
# Live Notion E2E (requires dedicated test workspace)
cp .env.example .env # set E2E_ROOT_PAGE_ID
npm run test:e2e
Symlink-dependent security tests are automatically skipped on platforms where symlink creation is unavailable (common on Windows without Developer Mode).
| Symptom | Likely cause | Fix |
|---|---|---|
NOTION_TOKEN is required |
Missing env var | Set token in MCP config env block or .env |
401 invalid_token (HTTP) |
Missing/wrong bearer | Set NOTION_MCP_BEARER on server; send Authorization: Bearer … |
outside the allowed workspace root |
File path escapes root | Set NOTION_MCP_WORKSPACE_ROOT or use absolute paths inside it |
| Redis warning on startup | Redis unreachable | Start Redis or set REDIS_ENABLED=false |
| Unknown property name | Stale/wrong schema | Call get_database first; check case sensitivity |
| Symlink tests skipped | OS restriction | Enable Windows Developer Mode or run on Linux/macOS |
Enable debug logging:
LOG_LEVEL=debug npm start
mainnpm run build && npm run lint && npm testSee docs/AUDIT.md for architecture context and known improvement areas.
How is this different from the official Notion MCP server?
The official server returns raw Notion JSON (~6–7× more tokens per page read). This server converts to markdown agents already understand, with round-trip fidelity for 24 block types.
Do I need Redis?
No. Redis is optional and improves horizontal scaling (shared schema cache, OAuth tokens across HTTP instances). Single-process stdio deployments work fine without it.
Is markdown round-trip lossless?
For supported block types, yes. Unsupported native blocks (e.g. synced_block, embedded databases) emit warnings so agents avoid destructive rewrites.
Does file upload work over HTTP?
No. file:// uploads are stdio-only for security. Use HTTPS URLs or stdio transport for local files.
What Node version is required?
Node.js 20 or later.
MIT — see LICENSE.