Notion Bot MCP Server

An MCP server that converts markdown to native Notion blocks. Write docs in your IDE, and they show up in Notion with proper headings, lists, and syntax-highlighted code — not plain text walls.

💡 Why This Exists

The Official Notion MCP treats all markdown as plain text. Your # Headings become regular paragraphs, code blocks lose formatting, and structured docs become unreadable. Notion Bot fixes that by converting markdown into proper Notion block types.

🛠️ How It Was Built

I built this to solve my own problem — the official MCP kept flattening my markdown. The solution combines the Notion API with custom parsing logic to translate markdown into native blocks. I used Claude AI to speed up implementation and iterate quickly on the conversion logic.

This isn't a replacement for the official MCP's broader functionality — it's a focused tool for when you want properly formatted docs from your IDE.

✨ Features

• Full markdown support — headings, lists, code blocks with syntax highlighting, inline formatting, quotes, and dividers
• Smart titles — automatically extracts the first H1 as the page title
• Works anywhere — available across all your Cursor workspaces, not tied to any repo
• Your code — runs locally, fully extensible

📋 Prerequisites

• Node.js 20+ (download) — check with node --version
• Cursor IDE (or any MCP-capable IDE)
• Notion account with workspace access

🚀 Installation

Step 1: Clone and Build

git clone https://github.com/thacherhussain/notion-bot-mcp.git
cd notion-bot-mcp
npm install && npm run build

Step 2: Set Up Notion Integration

1. Follow the steps to Create a Notion Integration

2. Copy your "Internal Integration Secret" to be added to the .env file

3. Share the pages/databases you want to use with this integration (sharing is inherited by child pages)

4. (Optional) Set default Parent Page and/or Database IDs in .env to skip passing them on each call

Step 3: Configure Environment Variables

cp .env.example .env

Then edit .env with your values:

NOTION_API_TOKEN=your-token-here
NOTION_DEFAULT_PARENT_PAGE_ID=your-default-page-id-here  # optional
NOTION_DEFAULT_DATABASE_ID=your-default-database-id-here  # optional

Auto-sync: On startup, the server automatically syncs your .env values to ~/.cursor/mcp.json. After the initial setup, just update .env and restart Cursor — no need to manually edit the MCP config.

Step 4: Configure MCP in Cursor

Initial MCP Config Setup (One-time):

You'll need to add the notion-bot server entry to ~/.cursor/mcp.json once:

{
  "mcpServers": {
    "notion-bot": {
      "command": "node",
      "args": ["[YOUR_PROJECT_PATH]/notion-bot-mcp/dist/index.js"]
    }
    ... other-mcp-servers ...
  }
}

Replace [YOUR_PROJECT_PATH] with the absolute path to this project directory.

Step 5: Restart Cursor

Close and reopen Cursor completely. Ask "What Notion tools are available?" to verify the tools loaded.

🔧 Tools Available

Tool	Description
create-page-from-markdown	Create a new page under a parent page
create-page-in-database	Create a new row/page in a database
append-markdown-to-page	Add content to the end of an existing page
update-page-with-markdown	Replace all content in a page (destructive)
test-notion-bot-mcp	Health check — tests API connection and parsing

All tools auto-convert markdown to native Notion blocks and extract the first H1 as the page title.

🎨 Supported Markdown Syntax

Markdown	Notion Block Type
# Heading 1	heading_1
## Heading 2	heading_2
### Heading 3	heading_3
Paragraph text	paragraph
- Bullet list	bulleted_list_item
1. Numbered list	numbered_list_item
```lang ... ```	code (with language detection)
> Quote	quote
---	divider
**bold**	Bold annotation
*italic*	Italic annotation
`code`	Code annotation
~~strikethrough~~	Strikethrough annotation
[text](url)	Link

Note: Notion only supports H1-H3. Headings H4 and deeper are converted to H3.

🎓 Usage Examples

Finding Page IDs: Open a page or database in Notion (web) → grab the ID from the URL:

• Page: notion.so/Page-Name-abc123def456 → ID is abc123def456
• Database: notion.so/data-base-id → ID is data-base-id

1. Create a page (under default parent)

Create a Notion page:

# Team Meeting

## Notes
- Discussed dog treat recipes
- Reviewed best local dog parks

2. Create a database page (in default database)

Create a database Notion page:

# Dog Name Generator

## Description
New feature implementation for picking the perfect dog name

3. Create from a local file

Create a Notion page from meeting-notes.md

📝 Technical Notes

Dependencies: @modelcontextprotocol/sdk, @notionhq/client, dotenv, marked, typescript

Security: Your Notion token lives in .env (git-ignored) and syncs to your local MCP config on startup.

After code changes: Run npm run build and restart Cursor.

🐛 Troubleshooting

Issue	Fix
Tools not appearing	Restart Cursor (full quit, not reload). Verify npm run build succeeded.
API errors	Check page ID, token validity, and that integration has page access.
Markdown not converting	Verify syntax matches supported features. Try simpler markdown first.

Logs appear in Cursor's output panel.

---

If you find this useful or have questions, feel free to open an issue or reach out on GitHub.

This project is licensed under the MIT License.