# memos-mcp（用于对 usesmemos/memos 进行CRUD的MCP服务）

> English version: [README.en.md](./README.en.md)

一个用 **Python** 实现的 Memos MCP 服务，对 [Memos](https://github.com/usememos/memos)
实例提供完整的增删改查（CRUD）。只依赖 `httpx` + 官方 `mcp` SDK。

所有敏感配置（Memos 地址、Access Token）放在 `.env` 里，**绝不写进代码**。

---

## 工具

| 工具 | 说明 | 关键参数 |
|------|------|----------|
| `memos_create` | 新建 memo | `content`(必填), `visibility`(可选, 默认 PRIVATE) |
| `memos_list` | 列出/筛选 memo | `pageSize`, `pageToken`, `filter`(CEL 表达式) |
| `memos_get` | 按 ID 取 memo | `id`(必填) |
| `memos_update` | 更新 memo | `id`(必填), `content`, `visibility`, `pinned` |
| `memos_delete` | 删除 memo | `id`(必填) |

---

## 安装

```bash
git clone <your-repo> memos-mcp
cd memos-mcp
bash install.sh          # 建 .venv、装依赖、生成 .env（从 .env.example）
vim .env                 # 填入 MEMOS_API_URL / MEMOS_TOKEN
```

```dotenv
MEMOS_API_URL=https://memos.yourdomain.com
MEMOS_TOKEN=your-access-token     # Memos: Settings > Access Tokens > Create
```

---

## 在 MCP 宿主中注册（stdio）

把 `command` 指向本项目的 `memos.sh`（会自动加载 `.env`）：

```json
{
  "mcpServers": {
    "memos": {
      "command": "/abs/path/to/memos-mcp/memos.sh",
      "args": []
    }
  }
}
```

> 也可由宿主直接注入 `MEMOS_API_URL` / `MEMOS_TOKEN`，本项目 server 会优先使用宿主注入的值。

### Hermes Agent

Hermes 通过 stdio 加载本服务。将 `command` 指向项目的 `memos.sh`（自动加载
`.env`），凭据通过 `env` 注入：

```bash
hermes config set mcp_servers.memos.command "/abs/path/to/memos-mcp/memos.sh"
hermes config set mcp_servers.memos.args ""
hermes config set mcp_servers.memos.env '{"MEMOS_API_URL": "https://memos.yourdomain.com", "MEMOS_TOKEN": "your-access-token"}'
hermes gateway restart
```

> `args` 必须留空字符串。凭据也可改为引用宿主 `.env` 变量（如
> `"MEMOS_TOKEN": "${MCP_MEMOS_API_KEY}"`），由 Hermes 启动时展开。

---

## 许可证

MIT