Content
# Mowen Notes MCP Server
This is a server based on the **Model Context Protocol (MCP)** for interacting with Mowen Notes software. Through this server, you can directly create, edit, and manage Mowen Notes in applications that support MCP (such as Cursor, Claude Desktop, etc.).
This project is co-created by Yizhanyan Community and Mowen.
## 🆕 Installation-Free Version Available (Beginner-Friendly)
### How to Use (Windows 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 Features: File upload support! You can now insert images, audio, and PDF files into notes, supporting both local files and remote URLs.**
## 🆕 New Feature Preview (v0.2.0)
### 📁 File Upload Support
⚠️ **Important: File paths must use absolute paths** because 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\\用户名\\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 formatted quote paragraphs"}
]
}
```
### 🔗 Internal Note Links
```python
{
"type": "note",
"note_id": "VPrWsE_-P0qwrFUOygGs8"
}
```
## Features
- 🔗 **MCP Protocol Compatibility**: Supports the latest MCP 1.9.1 version
- 📝 **Create Notes**: Unified rich text format, supports paragraphs, bold, highlight, links, quotes, and internal note links
- ✏️ **Edit Notes**: Unified rich text format, completely replaces note content
- 📁 **File Upload**: Supports image, audio, and PDF file uploads, both local files and remote URLs
- 💬 **Quote Paragraphs**: Create quote text blocks, supports rich text format
- 🔗 **Internal Note Links**: Reference other notes, create associations between notes
- 🔒 **Privacy Settings**: Set note permissions to public, private, or rule-based
- 🔄 **Key Management**: Reset API key function
- 🎨 **Unified Interface**: All note operations use a consistent rich text parameter format
## Quick Start
### Prerequisites
- Python 3.10+
- Mowen Pro membership account (API functionality is only available to Pro members)
- Mowen API key (obtained in the Mowen mini-program)
### Installation
#### 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: Install Dependencies Directly
```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 (Recommended)
If you used `pip install -e .` to install, 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
If you don't have the package installed, you can directly specify the file path:
```json
{
"mcpServers": {
"mowen-mcp-server": {
"command": "python",
"args": ["绝对路径/mowen-mcp-server/src/mowen_mcp_server/server.py"],
"env": {
"MOWEN_API_KEY": "${env:MOWEN_API_KEY}"
}
}
}
}
```
**Note**: Replace `绝对路径` 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 paragraph contains text nodes
- `auto_publish` (boolean, optional): Whether to automatically publish, defaults to false
- `tags` (string array, optional): List of note tags
**Supported Paragraph Types:**
1. **Normal Paragraph** (default): `{"texts": [...]}`
2. **Quote Paragraph**: `{"type": "quote", "texts": [...]}`
3. **Internal Note Link**: `{"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": "Linked text", "link": "https://example.com"}
]
},
{
"type": "quote",
"texts": [
{"text": "This is a quote 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\\用户名\\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): ID of the note to edit
- `paragraphs` (array, required): List of rich text paragraphs, will completely replace the original content
**Note:** This operation will completely replace the original content of the note, not append content. Supports all paragraph types (normal paragraph, quote paragraph, internal note link, file paragraph).
### 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 expire)
### 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 via MCP tool
create_note(
paragraphs=[
{
"texts": [
{"text": "Today I learned Python programming, focusing on asynchronous programming concepts"}
]
}
],
auto_publish=True,
tags=["Learning", "Python", "Programming"]
)
```
### Create a Rich Text Note
```python
# Call via MCP tool
create_note(
paragraphs=[
{
"texts": [
{"text": "Important reminder:", "bold": true},
{"text": "Tomorrow's meeting has been rescheduled"}
]
},
{
"texts": [
{"text": "See details:", "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 via MCP tool
create_note(
paragraphs=[
{
"texts": [
{"text": "Project Progress Report", "bold": true}
]
},
{
"type": "quote",
"texts": [
{"text": "Completed the main feature development this week,", "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 via MCP tool
create_note(
paragraphs=[
{
"texts": [
{"text": "Project screenshots and demos", "bold": true}
]
},
{
"type": "file",
"file_type": "image",
"source_type": "local",
"source_path": "C:\\Users\\user\\Desktop\\screenshot.png",
"metadata": {
"alt": "Project main interface screenshot",
"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": "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 via MCP tool
edit_note(
note_id="note_123456",
paragraphs=[
{
"texts": [
{"text": "Update:", "bold": true},
{"text": "Project progress is 80% complete"}
]
},
{
"type": "quote",
"texts": [
{"text": "See detailed report:", "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, each interface has the following limits:
| API | Quota | Rate Limit | Description |
| ------------- | ----------- | ---------- | --------------------------------------------------------------------------- |
| Create Note | 100 times/day | 1 time/sec | Only counted as 1 time when the call is successful, **i.e., 100 notes per day via API** |
| Edit Note | 1000 times/day| 1 time/sec | Only counted as 1 time when the call is successful, **i.e., 1000 edits per day via API** |
| Set Note Privacy| 100 times/day | 1 time/sec | Only counted as 1 time when the call is successful |
## 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 # Changelog
└── 墨问API.md # Detailed Mowen API documentation
```
## Related Documentation
- **Mowen API Online Documentation**: [https://mowen.apifox.cn/](https://mowen.apifox.cn/)
- **Local API Documentation**: Detailed Mowen API documentation can be found in the `墨问API.md` file in the project
- **MCP Protocol Documentation**: [Model Context Protocol](https://modelcontextprotocol.io/)
## FAQ
### Q: Why doesn't the module method work?
A: Make sure you have installed the package using `pip install -e .` or use the direct file path configuration method.
### Q: Where can I get 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: Not currently supported, you can only edit notes created through the API.
### Q: How do I use quote paragraphs and internal note links?
A: Quote paragraphs use the `{"type": "quote", "texts": [...]}` format, and internal note links use the `{"type": "note", "note_id": "Note ID"}` format. Quote paragraphs support all rich text formats (bold, highlight, link).
### Q: Where do I get the note_id for internal note links?
A: The note_id is the note ID returned when creating a note, or the ID of an existing note in Mowen. Note that you can only reference notes created through the API.
### Q: Why are there only paragraphs parameters and no simple content parameter?
A: We have unified the interface design, and using rich text format can support richer content. Even for simple text, you can easily use the paragraphs format: `[{"texts": [{"text": "Your text"}]}]`
### Q: How do I migrate from older versions of the API call?
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 the same.
### Q: Why does it say "File does not exist" when uploading a file?
A: **You must use an absolute path**. MCP Server and Client run in different working directories, and relative paths will fail to resolve.
- ✅ Correct: `"C:\\Users\\用户名\\Documents\\image.jpg"` (Windows)
- ✅ Correct: `"/Users/用户名/Documents/image.jpg"` (macOS/Linux)
- ❌ Incorrect: `"./image.jpg"` or `"image.jpg"` (relative path)
### Q: What file types are supported?
A: Three file types are supported:
- Image (image): .gif, .jpeg, .jpg, .png, .webp (maximum 50MB)
- Audio (audio): .mp3, .mp4, .m4a (maximum 200MB)
- PDF (pdf): .pdf (maximum 100MB)
### Q: What are the restrictions on remote URL file uploads?
A: Remote URLs are not restricted by path format, but the file must be publicly accessible and meet the file type and size restrictions.
## Development Contributions
Welcome to submit Issues and Pull Requests!
### 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 by an individual and is not affiliated with Mowen. Please ensure that you comply with Mowen's terms of service before use.
