Content
# Mowen Note MCP Server
This is a server based on the **Model Context Protocol (MCP)** for interacting with the Mowen Note software. Through this server, you can directly create, edit, and manage Mowen Notes in MCP-supported applications (such as Cursor, Claude Desktop, etc.).
This project is co-created by the Fireworks Community and Mowen.
## 🆕 Portable Version Launched (User-Friendly)
### Usage Instructions (Windows as an Example)
1. Download `mowen-mcp-server-windows-x64-v1.0.0.zip` and extract `mowen-mcp-server.exe`.
2. Modify the `command` value in the MCP client, replacing it with the path to the `mowen-mcp-server.exe` file.
```json
{
"mcpServers": {
"mowen-mcp-server": {
"command": "D:\\mowen\\mowen-mcp-server.exe",
"args": [],
"env": {
"MOWEN_API_KEY": "xxxxxxxxxxxxxxx"
}
}
}
}
```
**✨ Latest Version Feature: File Upload Support! You can now insert images, audio, and PDF files into your notes, supporting both local files and remote URLs for uploads.**
## 🆕 New Feature Preview (v0.2.0)
### 📁 File Upload Support
⚠️ **Important: File paths must use absolute paths**, as the MCP Server and Client run in different working directories.
```python
# Local image file
{
"type": "file",
"file_type": "image",
"source_type": "local",
"source_path": "C:\\Users\\Username\\Documents\\image.jpg", # Windows absolute path
"metadata": {
"alt": "Image description",
"align": "center"
}
}
# Remote audio file (URL is not path-restricted)
{
"type": "file",
"file_type": "audio",
"source_type": "url",
"source_path": "https://example.com/audio.mp3",
"metadata": {
"show_note": "00:00 Start\n01:30 Main Content"
}
}
```
### 📝 Quote Paragraphs
```python
{
"type": "quote",
"texts": [
{"text": "Important Reminder:", "bold": true},
{"text": "Supports rich text format for quoted paragraphs"}
]
}
```
### 🔗 Internal Link Notes
```python
{
"type": "note",
"note_id": "VPrWsE_-P0qwrFUOygGs8"
}
```
## Features
- 🔗 **MCP Protocol Compatibility**: Supports the latest MCP version 1.9.1
- 📝 **Create Notes**: Unified rich text format, supporting paragraphs, bold, highlights, links, quotes, and internal link notes
- ✏️ **Edit Notes**: Unified rich text format, completely replaces note content
- 📁 **File Upload**: Supports uploading images, audio, and PDF files, with both local files and remote URLs
- 💬 **Quote Paragraphs**: Create quoted text blocks, supporting rich text format
- 🔗 **Internal Link Notes**: Reference other notes, creating associations between notes
- 🔒 **Privacy Settings**: Set notes to public, private, or rule-based visibility
- 🔄 **Key Management**: Reset API key functionality
- 🎨 **Unified Interface**: All note operations use a consistent rich text parameter format
## Quick Start
### Prerequisites
- Python 3.10+
- Mowen Pro membership account (API features are only available to Pro members)
- Mowen API key (obtainable in the Mowen mini-program)
### Installation Methods
#### Method 1: Install from Source (Recommended)
1. **Clone the Project**:
```bash
git clone https://github.com/z4656207/mowen-mcp-server.git
cd mowen-mcp-server
```
2. **Install Dependencies**:
```bash
pip install -e .
```
#### Method 2: Directly Install Dependencies
```bash
pip install mcp httpx pydantic
```
### Configure API Key
#### Windows PowerShell
```powershell
$env:MOWEN_API_KEY="Your Mowen API Key"
```
#### Linux/macOS
```bash
export MOWEN_API_KEY="Your Mowen API Key"
```
#### Persistent Settings
Create a `.env` file:
```
MOWEN_API_KEY=Your Mowen API Key
```
### Configure MCP Client
#### Method 1: Module Installation Method (Recommended)
If you installed using `pip install -e .`, add the following in Cursor settings:
```json
{
"mcpServers": {
"mowen-mcp-server": {
"command": "python",
"args": ["-m", "mowen_mcp_server.server"],
"env": {
"MOWEN_API_KEY": "${env:MOWEN_API_KEY}"
}
}
}
}
```
#### Method 2: Direct File Path Method
If you did not install the package, you can specify the file path directly:
```json
{
"mcpServers": {
"mowen-mcp-server": {
"command": "python",
"args": ["absolute/path/mowen-mcp-server/src/mowen_mcp_server/server.py"],
"env": {
"MOWEN_API_KEY": "${env:MOWEN_API_KEY}"
}
}
}
}
```
**Note**: Please replace `absolute/path` with your actual project path, for example:
- Windows: `"D:/CODE/mowen-mcp-server/src/mowen_mcp_server/server.py"`
- macOS/Linux: `"/home/user/mowen-mcp-server/src/mowen_mcp_server/server.py"`
## Available Tools
### create_note
Create a new Mowen Note using a unified rich text format.
**Parameters:**
- `paragraphs` (array, required): List of rich text paragraphs, each containing text nodes
- `auto_publish` (boolean, optional): Whether to auto-publish, default is false
- `tags` (array of strings, optional): List of note tags
**Supported Paragraph Types:**
1. **Normal Paragraph** (default): `{"texts": [...]}`
2. **Quote Paragraph**: `{"type": "quote", "texts": [...]}`
3. **Internal Link Note**: `{"type": "note", "note_id": "Note ID"}`
4. **File Paragraph**: `{"type": "file", "file_type": "image|audio|pdf", "source_type": "local|url", "source_path": "absolute path", "metadata": {...}}`
**Paragraph Format Example:**
```json
[
{
"texts": [
{"text": "Normal text"},
{"text": "Bold text", "bold": true},
{"text": "Highlighted text", "highlight": true},
{"text": "Link text", "link": "https://example.com"}
]
},
{
"type": "quote",
"texts": [
{"text": "This is a quoted paragraph"},
{"text": "Supports rich text", "bold": true}
]
},
{
"type": "note",
"note_id": "VPrWsE_-P0qwrFUOygxxx"
},
{
"type": "file",
"file_type": "image",
"source_type": "local",
"source_path": "C:\\Users\\Username\\Documents\\image.jpg",
"metadata": {
"alt": "Image description",
"align": "center"
}
}
]
```
**Simple Text Example:**
```json
[
{
"texts": [
{"text": "This is a simple text content"}
]
}
]
```
### edit_note
Edit the content of an existing note using a unified rich text format.
**Parameters:**
- `note_id` (string, required): The ID of the note to edit
- `paragraphs` (array, required): List of rich text paragraphs that will completely replace the original content
**Note:** This operation will completely replace the original content of the note, not append to it. Supports all paragraph types (normal paragraphs, quote paragraphs, internal link notes, file paragraphs).
### set_note_privacy
Set the privacy permissions of a note.
**Parameters:**
- `note_id` (string): Note ID
- `privacy_type` (string): Privacy type (public/private/rule)
- `no_share` (boolean, optional): Whether to prohibit sharing (only valid for rule type)
- `expire_at` (integer, optional): Expiration timestamp (only valid for rule type, 0 means never expires)
### reset_api_key
Reset the Mowen API key.
**Note:** This operation will immediately invalidate the current key.
## Usage Examples
### Create a Simple Text Note
```python
# Call through MCP tool
create_note(
paragraphs=[
{
"texts": [
{"text": "Today I learned Python programming, focusing on the concept of asynchronous programming"}
]
}
],
auto_publish=True,
tags=["Learning", "Python", "Programming"]
)
```
### Create a Rich Text Note
```python
# Call through MCP tool
create_note(
paragraphs=[
{
"texts": [
{"text": "Important Reminder:", "bold": true},
{"text": "Tomorrow's meeting has been rescheduled"}
]
},
{
"texts": [
{"text": "For details, please check:", "highlight": true},
{"text": "Meeting Notice", "link": "https://example.com/meeting"}
]
}
],
auto_publish=True,
tags=["Meeting", "Notice"]
)
```
### Create a Complex Note with Quotes and Internal Links
```python
# Call through MCP tool
create_note(
paragraphs=[
{
"texts": [
{"text": "Project Progress Report", "bold": true}
]
},
{
"type": "quote",
"texts": [
{"text": "This week we completed the main feature development,", "highlight": true},
{"text": "See technical documentation", "link": "https://docs.example.com"}
]
},
{
"type": "note",
"note_id": "VPrWsE_-P0qwrFUOygGs8"
},
{
"texts": [
{"text": "Next week's plan: Start testing phase"}
]
}
],
auto_publish=True,
tags=["Project", "Progress", "Report"]
)
```
### Create a Note with Files
```python
# Call through MCP tool
create_note(
paragraphs=[
{
"texts": [
{"text": "Project screenshots and demo", "bold": true}
]
},
{
"type": "file",
"file_type": "image",
"source_type": "local",
"source_path": "C:\\Users\\user\\Desktop\\screenshot.png",
"metadata": {
"alt": "Screenshot of the main interface",
"align": "center"
}
},
{
"texts": [
{"text": "Demo video (audio):"}
]
},
{
"type": "file",
"file_type": "audio",
"source_type": "url",
"source_path": "https://example.com/demo.mp3",
"metadata": {
"show_note": "00:00 Project Introduction\n01:30 Feature Demonstration\n03:00 Summary"
}
},
{
"texts": [
{"text": "See detailed documentation in the attachment:"}
]
},
{
"type": "file",
"file_type": "pdf",
"source_type": "local",
"source_path": "C:\\Users\\user\\Documents\\project_doc.pdf"
}
],
auto_publish=True,
tags=["Project", "Documentation", "Demo"]
)
```
### Edit a Note
```python
# Call through MCP tool
edit_note(
note_id="note_123456",
paragraphs=[
{
"texts": [
{"text": "Update:", "bold": true},
{"text": "Project progress has reached 80%"}
]
},
{
"type": "quote",
"texts": [
{"text": "For detailed reports, please check:", "highlight": true},
{"text": "Project Documentation", "link": "https://example.com/report"}
]
},
{
"type": "note",
"note_id": "related_note_id"
}
]
)
```
## API Quota Limits
According to the Mowen API documentation, the following limits apply to each interface:
| API | Quota | Rate Limit | Description |
|-------------|-------------|------------|--------------------------------------------------|
| Note Creation | 100 times/day | 1 time/second | Only successful calls count as 1 time, **i.e., you can create 100 notes based on the API each day** |
| Note Editing | 1000 times/day | 1 time/second | Only successful calls count as 1 time, **i.e., you can edit notes 1000 times based on the API each day** |
| Note Settings | 100 times/day | 1 time/second | Only successful calls count as 1 time |
## Project Structure
```
mowen-mcp-server/
├── src/
│ └── mowen_mcp_server/
│ ├── __init__.py # Package initialization
│ ├── server.py # MCP server main program
│ └── config.py # Configuration management
├── examples/
│ └── create_note/ # Create note examples
├── pyproject.toml # Project configuration
├── README.md # Project documentation
├── CHANGELOG.md # Change log
└── MowenAPI.md # Detailed Mowen API documentation
```
## Related Documentation
- **Mowen API Online Documentation**: [https://mowen.apifox.cn/](https://mowen.apifox.cn/)
- **Local API Documentation**: For detailed Mowen API documentation, please refer to the `MowenAPI.md` file in the project
- **MCP Protocol Documentation**: [Model Context Protocol](https://modelcontextprotocol.io/)
## Frequently Asked Questions
### Q: Why can't the module method run?
A: Please ensure you have installed the package using `pip install -e .`, or use the direct file path configuration method.
### Q: Where can I obtain the API key?
A: Log in to the Mowen mini-program, find the API key in the developer module on your personal homepage, Pro membership is required.
### Q: Can I edit notes created by the mini-program?
A: Currently, it is not supported; you can only edit notes created via the API.
### Q: How to use quote paragraphs and internal link notes?
A: Use `{"type": "quote", "texts": [...]}` format for quote paragraphs, and `{"type": "note", "note_id": "Note ID"}` format for internal link notes. Quote paragraphs support all rich text formats (bold, highlight, link).
### Q: Where can I get the note_id for internal link notes?
A: The note_id is the ID returned when creating a note, or the ID of an existing note in Mowen. Note that only notes created via the API can be referenced.
### Q: Why is there only a paragraphs parameter and no simple content parameter?
A: We have unified the interface design; using rich text format allows for richer content. Even for simple text, it can easily be formatted using paragraphs: `[{"texts": [{"text": "Your text"}]}]`
### Q: How to migrate from old version API calls?
A: If you previously used `create_note(content="text")`, you now need to change it to `create_note(paragraphs=[{"texts": [{"text": "text"}]}])`. The rich text functionality remains unchanged.
### Q: Why does it prompt "File does not exist" during file upload?
A: **You must use absolute paths**. The MCP Server and Client run in different working directories, and relative paths will fail to resolve.
- ✅ Correct: `"C:\\Users\\Username\\Documents\\image.jpg"` (Windows)
- ✅ Correct: `"/Users/Username/Documents/image.jpg"` (macOS/Linux)
- ❌ Incorrect: `"./image.jpg"` or `"image.jpg"` (relative paths)
### Q: What file types are supported?
A: Three file types are supported:
- Images (image): .gif, .jpeg, .jpg, .png, .webp (max 50MB)
- Audio (audio): .mp3, .mp4, .m4a (max 200MB)
- PDF (pdf): .pdf (max 100MB)
### Q: Are there any restrictions on remote URL file uploads?
A: Remote URLs are not restricted by path format, but the files must be publicly accessible and meet the file type and size restrictions.
## Development Contribution
Contributions via Issues and Pull Requests are welcome!
### Development Environment Setup
1. Clone the project
2. Install development dependencies: `pip install -e .`
3. Set the API key environment variable
4. Run tests
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Disclaimer
This project is a third-party tool developed independently and is not affiliated with Mowen. Please ensure compliance with Mowen's terms of service before use.
