Content
# NotionMCP Light
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 (which reads and writes Markdown in block units, consuming LLM tokens). It provides an unofficial MCP server that can directly synchronize Markdown files and Notion pages/databases via the API without using tokens.
## Features
- **Markdown → Notion**
- Recognizes H1 as the page title
- Creates Markdown content as a Notion page or database page
- Database ID can be specified
- Directly uses the Notion API (no tokens used)
- **Notion → Markdown**
- Converts the specified page or database page to Markdown format
- Outputs the title as H1
- Converts the block structure to Markdown
- Saves to a file
- **MCP Server Support**
- Compliant with Model Context Protocol (MCP)
- Provides endpoints that can be called from AI tools such as Cursor and Cline
- Operates on JSON-RPC over stdio
## Installation
### Install Dependencies
```bash
# Install uv first if it is not installed
# pip install uv
# Install dependencies
uv sync
```
### Setting the Notion API Token
1. Create an account at [Notion Developers](https://developers.notion.com/) and obtain an API token.
2. Set it in the environment variables or create a `.env` file and set the token.
```bash
# Example of .env file
NOTION_TOKEN=your_notion_api_token
```
## Usage
### Starting the MCP Server
#### Using uv (Recommended)
```bash
uv run python -m src.main
```
Or, to specify the token directly:
```bash
uv run python -m src.main --token your_notion_api_token
```
#### Using Regular Python
```bash
python -m src.main
```
Or, to specify 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 such as Cline/Cursor/Claude Code, add the following settings to the JSON file for each tool's MCP server configuration:
```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.
## How to Use 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 licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
MCP Store
