Content
# Notion Prompts MCP Server
This is a server that uses the Model Context Protocol (MCP) standard, providing access to prompts stored in a Notion database.
## Features
- **Prompt Resource List**: Provides all available prompts in MCP resource format
- **Prompt Retrieval**: Retrieve a single prompt by ID or name
- **Prompt Composition**: Combine user input with prompt templates
- **Category Management**: Supports grouping and querying prompts by category
- **Search Functionality**: Allows searching for prompts by name, description, and content
- **Caching System**: Built-in caching mechanism to optimize performance and reduce API calls
- **Configurable**: Supports configuration via environment variables or command-line arguments
- **Processing Modes**: Supports various prompt processing methods to avoid LLM (Large Language Model) overreach
## Installation
```bash
# Clone the repository
git clone https://github.com/BaoxingZhang/mcp-server-notion-prompt
cd mcp-server-notion-prompt
# Install dependencies
npm install
# Build the project
npm run build
```
## Configuration
### 1. Create Notion Integration
1. Visit the [Notion Developer Portal](https://www.notion.so/my-integrations)
2. Click "+ New integration"
3. Fill in the basic information
4. In the "Capabilities" section, ensure "Read content" is checked
5. Click "Submit" to create the integration
6. After creation, copy the displayed "Internal Integration Token" (starting with "ntn_"), which is your NOTION_API_KEY
### 2. Create Notion Database
1. Create a new page in Notion
2. Type /database and select "Table Database"
3. Set the following properties:
- Name (Title property): The name of the prompt
- Content (Text property): The content of the prompt
- Description (Text property): The description or purpose of the prompt
- Category (Multi-select property): The category of the prompt (optional)
4. Open your prompt database in Notion
5. Find the database ID in the page URL (`https://www.notion.so/workspace/123456abcdef...`, where "123456abcdef..." is the database ID)
6. Record this ID, as it will be used as NOTION_DATABASE_ID
7. Share the database with the integration (open the prompt database, click the "..." menu in the upper right corner, select "Add connections", and find and select the integration you just created in the search box)
### 3. Server Configuration
The server requires the following configuration:
- **NOTION_API_KEY**: Your Notion API key
- **NOTION_DATABASE_ID**: The Notion database ID where prompts are stored
- **PROMPT_HANDLING_MODE**: The processing mode after prompt composition (optional, defaults to process_locally)
- `return_only`: Only returns the composed prompt text without additional processing
- `process_locally`: Indicates that the client should process the prompt using the current context's LLM
- `call_external_api`: The server calls an external API to process the prompt (requires additional configuration)
These can be provided via environment variables or command-line arguments:
```bash
# Using environment variables
export NOTION_API_KEY="your_api_key_here"
export NOTION_DATABASE_ID="your_database_id_here"
export LOG_LEVEL="INFO" # Optional, defaults to INFO
export CACHE_EXPIRY_TIME="300000" # Optional, defaults to 5 minutes (300000ms)
export PROMPT_HANDLING_MODE="process_locally" # Optional, defaults to process_locally
# Start the server
npm start
# Or use command-line arguments
npm start -- --notion_api_key=your_api_key_here --notion_database_id=your_database_id_here --prompt_handling_mode=return_only
```
## Notion Database Structure
The Notion database should contain the following properties:
- **Name** (Title): The name of the prompt
- **Content** (Rich Text): The content of the prompt, which can include the `{{USER_INPUT}}` placeholder
- **Description** (Rich Text): The description of the prompt
- **Category** (Select): The category of the prompt
## Prompt Variables
In the prompt content, you can use the following variables:
- `{{USER_INPUT}}`: Will be replaced by user input
- `{{CURRENT_DATE}}`: Current date
- `{{CURRENT_TIME}}`: Current time
- `{{CURRENT_DATETIME}}`: Current date and time
- `{{PROMPT_NAME}}`: Name of the prompt
## MCP Tools
This server provides the following MCP tools:
1. **list_prompts**: List all available prompts
2. **get_prompt_by_name**: Retrieve a prompt by name
3. **compose_prompt**: Integrate user input into the prompt template
4. **process_composed_prompt**: Process the composed prompt
5. **process_category_prompts**: Process all prompts in a specified category
6. **refresh_prompts**: Refresh the prompt cache
7. **get_prompts_by_category**: Retrieve prompts of a specific category
8. **search_prompts**: Search for prompts (by name, description, and content)
9. **list_categories**: List all available prompt categories
## Development
```bash
# Run the development version
npm run dev
# Build
npm run build
# Run tests
npm test
```
## Usage Examples
```
# Retrieve a specific prompt
Please use the get_prompt_by_name tool to retrieve the prompt named "Translation Assistant".
# Combine prompt with user input
Please use the compose_prompt tool, with the prompt name "Translation Assistant" and user input "Hello, I am learning to use Cursor with MCP."
# Directly use prompt to process content
Please use the prompt named "Translation Assistant" to translate the following text: Hello, I am learning to use Cursor with MCP.
# Refresh cache
Please use the refresh_prompts tool to refresh the prompt cache.
# Use category to call multiple prompts
Call prompts in the category "Seven Weapons" and output 7 SVG cards, with the input content: "Just read the news, no discussion~".
# Combine processing results
Call prompts in the category "Seven Weapons", first output 7 SVG cards separately, then integrate the 7 SVG cards into one HTML, with the input content: "Just read the news, no discussion~".
# AI self-selection
Life, love, and laughter (Osho)
Select a suitable weapon from the Seven Weapons category to output.
```
## Server JSON Example
```
{
"mcpServers": {
"notion-prompts": {
"command": "node",
"args": [
"D:\\project\\mcp-project\\mcp-server-notion-prompt\\build\\index.js"
],
"env": {
"NOTION_API_KEY": "ntn_xxx",
"NOTION_DATABASE_ID": "1ccxxx"
}
}
}
}
```
## License
MIT
