# flomo MCP Server

[![PyPI version](https://badge.fury.io/py/flomo-mcp-server.svg)](https://pypi.org/project/flomo-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/pypi/pyversions/flomo-mcp-server.svg)](https://pypi.org/project/flomo-mcp-server/)

MCP server for [flomo](https://flomoapp.com) - 让 AI 工具（如 Claude Code、ChatGPT）能够快速向 flomo 添加笔记。

## 什么是 MCP？

MCP (Model Context Protocol) 是 Anthropic 推出的开放协议，让 AI 模型能够与外部工具和服务进行交互。通过这个 server，你可以让 Claude 等AI 工具直接帮你记录想法到 flomo。

## 功能

- ✅ 向 flomo 添加笔记
- ✅ 支持 Markdown 格式
- ✅ 支持 #标签
- ✅ 通过环境变量配置 API URL
- ✅ 完善的错误处理

## 安装

### 使用 uvx（推荐，无需预安装）

```bash
uvx --from flomo-mcp-server flomo-mcp
```

### 使用 pip

```bash
pip install flomo-mcp-server
flomo-mcp
```

### 使用 uv

```bash
uv pip install flomo-mcp-server
flomo-mcp
```

## 配置

### Claude Code

在 Claude Code 的 `settings.json` 中添加：

```json
{
  "mcpServers": {
    "flomo": {
      "command": "uvx",
      "args": ["--from", "flomo-mcp-server", "flomo-mcp"],
      "env": {
        "FLOMO_API_URL": "https://flomoapp.com/iwh/你的专属URL/"
      }
    }
  }
}
```

### 其他 MCP 客户端

同样配置 `FLOMO_API_URL` 环境变量即可使用。

### 获取 flomo API URL

1. 登录 [flomo 网页版](https://flomoapp.com)
2. 进入 **设置** → **API**
3. 复制你的专属 API URL

## 使用示例

在 Claude Code 中：

> "帮我记录一条 flomo：今天学到了 MCP 协议的基本原理 #学习"

Claude 会调用 `add_flomo` 工具，将内容添加到你的 flomo。

## 工具说明

### add_flomo

向 flomo 添加一条笔记。

**参数：**
- `content` (必填): 要记录的内容，支持 Markdown 格式，可使用 #标签

**返回：**
- 成功: "已成功添加到 flomo"
- 失败: 错误描述信息

## API 限制

通过 API 每天最多发布 **100 条**，此限制由 flomo API 自动处理。

## 开发

```bash
# 克隆仓库
git clone https://github.com/Jiraiya8/flomo-mcp-server.git
cd flomo-mcp-server

# 安装开发依赖
uv sync

# 运行测试
uv run pytest tests/ -v

# 本地运行
FLOMO_API_URL="https://flomoapp.com/iwh/你的URL/" uv run flomo-mcp
```

## Links

- [PyPI](https://pypi.org/project/flomo-mcp-server/)
- [GitHub](https://github.com/Jiraiya8/flomo-mcp-server)
- [flomo 官网](https://flomoapp.com)
- [MCP 协议](https://modelcontextprotocol.io)

## License

MIT License - 详见 [LICENSE](LICENSE) 文件