Content
# Flomo Note MCP Service
This is a Model Context Protocol (MCP) service built using the FastMCP framework, allowing AI assistants (such as Claude, Cherry Studio, etc.) to send notes to Flomo and query historical sending records. This service acts as a bridge between the AI assistant and the Flomo note application, enabling you to quickly record inspirations and ideas through conversation.
## Feature Overview
- **Send Notes to Flomo**: Directly send note content to your Flomo account through conversation.
- **Tag Support**: Add tags for categorization, automatically converting them to Flomo's #tag format.
- **Historical Record Query**: Search historical sending records by content or tag.
- **Automatic Synchronization**: Notes are saved to both Flomo and locally, achieving two-way backup.
## Quick Start
### 1. Installation Preparation
**System Requirements**:
- Python 3.8+
- pip package manager
- Valid Flomo Webhook URL
**Installation Steps**:
1. Clone or download this project to your local machine.
2. Install necessary dependencies:
```bash
pip install -r requirements.txt
```
3. Configure the Flomo Webhook URL (see the configuration section below).
### 2. Configure the Service
Open the `config.py` file and modify the following configuration items as needed:
```python
# Flomo API Configuration - Must replace with your own Webhook URL
FLOMO_WEBHOOK_URL = "https://flomoapp.com/iwh/yourID/yourWEBHOOK_KEY/"
# Data Storage Path - Usually does not need modification
DATA_DIR = "data" # Data storage directory
NOTES_FILE = os.path.join(DATA_DIR, "notes.json") # Historical record filename
# Default Tags - You can add your commonly used tags
DEFAULT_TAGS = [] # For example ["Important", "Work", "Study"]
# SSE Service Configuration - Modify if the port is occupied
SSE_PORT = 3000 # Default port
SSE_HOST = "0.0.0.0" # Listening address
```
**Steps to Configure Flomo Webhook URL**:
1. Log in to your Flomo account.
2. Visit the API page: https://flomoapp.com/mine?source=incoming_webhook
3. Click "Add New Webhook".
4. Copy the generated URL.
5. Paste this URL into the `FLOMO_WEBHOOK_URL` section of the configuration file.
### 3. Start the Service
There are two ways to start the service, choose according to your needs:
**Method 1: Stdio Mode (Recommended)**
```bash
./start_flomo.sh
```
**Method 2: SSE Mode (Advanced Use)**
```bash
./start_flomo.sh --sse --port 3000
```
### 4. Configure in AI Assistant
#### Claude Desktop Configuration Method
1. Open the Claude desktop application.
2. Go to settings -> Developer.
3. Click the option "Edit Config".
4. Navigate to the Claude directory and open the file "claude_desktop_config.json".
5. Fill in the following information:
```json
{
"mcpServers": {
"ai2flomo": {
"name": "Flomo Note Service",
"type": "stdio",
"description": "A tool for adding and managing notes, supports synchronization with Flomo",
"isActive": true,
"command": "/Users/username/workspace/mcp_space/ai2flomo/start_flomo.sh",
"args": [],
"env": {
"PATH": "/opt/miniconda3/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
}
}
}
}
```
6. Replace the path of the "start_flomo.sh" file and the environment variable "env" with your computer's settings.
7. Click "Save".
#### Cherry Studio Configuration Method
1. Open the Cherry Studio application.
2. Click the "Settings" icon.
3. Select "MCP Servers" from the left menu.
4. Click the "Add Server" button.
5. Fill in the following information:
- **Name**: Flomo Note Service
- **Description**: Send notes to Flomo and manage historical records through AI assistant.
- **Type**: Standard Input/Output (stdio)
- **Command**: Fill in the full path of the `start_flomo.sh` script.
- **Environment Variables**: You can fill in your system's environment variables.
6. Click "Save".
7. Toggle the switch next to the "Save" button to confirm that the service can connect properly.
**Cherry Studio JSON Configuration Example**:
In Cherry Studio, you can also directly edit the JSON configuration. Click the "Edit JSON" button to see a configuration similar to the following:
```json
{
"mcpServers": {
"MDzXVj9bhliofwJ8eCHs9": {
"name": "Flomo Note Service",
"type": "stdio",
"description": "A tool for adding and managing notes, supports synchronization with Flomo",
"isActive": true,
"command": "/Users/username/workspace/mcp_space/ai2flomo/start_flomo.sh",
"args": [],
"env": {
"PATH": "/opt/miniconda3/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
}
}
}
}
```
Make sure to replace the path `/Users/username/workspace/mcp_space/ai2flomo/start_flomo.sh` with the actual path of the `start_flomo.sh` script on your system.
If you are using SSE mode, the configuration method is slightly different:
1. Select "Type" as "SSE".
2. In the "URL" field, enter: `http://localhost:3000/sse` (adjust if you changed the port number).
3. Other steps are the same as above.
## User Guide
Once the service is started and configured in the AI assistant, you can use it in the following ways:
### Send Notes to Flomo
Simply tell the AI assistant what content you want to record:
- "Send 'This idea is interesting, I should research it further' to Flomo."
- "Help me add a note: 'I learned the basics of the MCP protocol today', tagged with 'Study Programming'."
### Search Historical Records
You can search previously sent notes by content or tag:
- "Find historical sending records containing 'Python'."
- "Show all historical sending records tagged with 'Study'."
- "List all tags from historical sending records."
- "Display my last 5 sent records."
## Project Structure
```
.
├── app.py # Main program file, contains all MCP tools and resource definitions
├── config.py # Configuration file, contains API keys, paths, and other settings
├── start_flomo.sh # Startup script
├── requirements.txt # Project dependencies
├── data/ # Data storage directory
│ └── notes.json # Historical sending records data file
├── logs/ # Log directory
└── README.md # Project documentation
```
## Technical Details
### API and Tools
The service provides the following MCP tools and resources:
#### Tools
1. **send_to_flomo(content, tags)**
- Sends notes to Flomo and saves them locally.
- Parameters:
- `content`: Note content.
- `tags`: Tags, separated by spaces.
2. **search_notes(query, tag)**
- Searches historical sending records.
- Parameters:
- `query`: Content search keyword.
- `tag`: Tag search keyword.
3. **get_all_tags()**
- Retrieves a list of all tags used in historical sending records.
#### Resources
1. **notes://recent**
- Retrieves the last 5 historical sending records.
2. **notes://{note_id}**
- Retrieves a specific historical sending record by ID.
### Data Storage
The service uses a simple JSON file for storage, located at `data/notes.json`. Each record contains:
- Unique ID
- Content
- List of tags
- Creation and update timestamps
### Tag Handling
- Input Format: Tags are separated by spaces, such as `"Study Programming Python"`.
- Flomo Format: Automatically converted to Flomo's #tag format, such as `#Study #Programming #Python`.
- Default Tags: If `DEFAULT_TAGS` is set in the configuration file, these tags will be automatically added to each note.
## Frequently Asked Questions
**Q: Where can I find my Flomo Webhook URL?**
A: Log in to the Flomo website and visit https://flomoapp.com/mine?source=incoming_webhook to view and create it.
**Q: What should I do if sending notes fails?**
A: Check if your Webhook URL is correct and if your network connection is stable. Error messages will be displayed in the service logs.
**Q: How can I add default tags?**
A: Edit the `config.py` file and modify the `DEFAULT_TAGS` list, such as `DEFAULT_TAGS = ["Daily", "AI Assistant"]`.
**Q: How can I back up historical sending records?**
A: All records are stored in the `data/notes.json` file, which can be backed up regularly.
## About MCP
Model Context Protocol (MCP) is a standardized protocol that allows AI models to interact securely with external tools and services. Through MCP, AI assistants can:
1. Use Tools - Perform actions, such as sending notes to Flomo.
2. Access Resources - Retrieve information, such as historical sending records.
3. Use Prompt Templates - Interact according to predefined patterns.
## Reference Resources
- [Flomo Official Website](https://flomoapp.com/)
- [Flomo API Documentation](https://help.flomoapp.com/extension/api.html)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
