Content
NotionMCP Light is a Model Context Protocol (MCP) server that synchronizes Markdown files and Notion pages using the Notion API.
## Overview
This project was developed to address the inefficiencies of the official Notion Model Context Protocol (MCP) server (reading and writing Markdown on a block-by-block basis, consuming LLM tokens). It provides an unofficial MCP server that allows direct synchronization of Markdown files and Notion pages/databases via the API without using tokens.
## Features
- **Markdown → Notion**
- Recognizes H1 as the page title
- Creates Notion pages or database pages from Markdown content
- Allows specifying a database ID
- Directly uses the Notion API (token not used)
- **Notion → Markdown**
- Converts specified pages or database pages to Markdown format
- Outputs the title as H1
- Converts block structure to Markdown
- Saves to file
- **MCP Server Support**
- Complies with Model Context Protocol (MCP)
- Provides endpoints callable from AI tools like Cursor and Cline
- Operates based on JSON-RPC over stdio
## Installation
### Install Dependencies
```bash
# Install uv first if not installed
# pip install uv
# Install dependencies
uv sync
```
### Set Up Notion API Token
1. Create an account at [Notion Developers](https://developers.notion.com/) and obtain an API token.
2. Set it as an environment variable or create a `.env` file to set the token.
```bash
# Example .env file
NOTION_TOKEN=your_notion_api_token
```
## Usage
### Start MCP Server
#### Using uv (recommended)
```bash
uv run python -m src.main
```
Or, if specifying the token directly:
```bash
uv run python -m src.main --token your_notion_api_token
```
#### Using regular Python
```bash
python -m src.main
```
Or, if specifying the token directly:
```bash
python -m src.main --token your_notion_api_token
```
### Configuration in Cline/Cursor
To use NotionMCP Light with AI coding tools like Cline/Cursor/Claude Code, add the following configuration to the JSON file for MCP server settings of each tool:
```json
{
"mcpServers": {
"notion-mcp-light": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/notion-mcp-light",
"-m",
"src.main"
],
"env": {
"NOTION_TOKEN": "your_notion_api_token"
}
}
}
}
```
Replace `/path/to/notion-mcp-light` with the installation directory of NotionMCP Light and `your_notion_api_token` with your Notion API token.
## Using MCP Tools
NotionMCP Light provides the following MCP tools:
### uploadMarkdown
Uploads a Markdown file and creates it as a Notion page.
```json
{
"jsonrpc": "2.0",
"method": "uploadMarkdown",
"params": {
"filepath": "path/to/markdown.md",
"database_id": "optional_database_id",
"page_id": "optional_parent_page_id"
},
"id": 1
}
```
### downloadMarkdown
Downloads a Notion page and saves it as a Markdown file.
```json
{
"jsonrpc": "2.0",
"method": "downloadMarkdown",
"params": {
"page_id": "notion_page_id",
"output_path": "path/to/output.md"
},
"id": 2
}
```
## License
This project is published under the MIT License. Please refer to the [LICENSE](LICENSE) file for details.
Connection Info
You Might Also Like
Continue
Continue is an open-source project for seamless server management.
repomix
Repomix packages your codebase into AI-friendly formats for enhanced coding.
Mastra
Mastra is an AI-powered framework developed by the Gatsby team.
Blender
BlenderMCP integrates Blender with Claude AI for enhanced 3D modeling.
cua
Cua is a cross-platform application built with Python and Swift, designed for macOS.
fastapi_mcp
FastAPI-MCP exposes FastAPI endpoints as Model Context Protocol tools with...