Mem.ai 的 MCP 服务器
一个可投入生产的模型上下文协议(MCP)服务器,为AI助手提供智能访问能力 Mem.ai(可译为“记忆人工智能”或根据具体语境调整为更贴切的表述,但直接保留原英文形式“Mem.ai”在中文中也是可接受的,尤其是在科技或特定领域术语中)的知识管理平台。
✨ 特点/功能
- 📝(笔记/待办事项的符号,可理解为“记录”或“待办事项”) 笔记管理创建、读取和删除结构化的Markdown笔记
- 📁 文件夹 集合将笔记组织成可搜索的集合
- 🔒 表示“锁”或“安全”的符号,常用于表示信息或账户的安全保护状态。 类型安全完整的类型提示和Pydantic验证
- ⚡(闪电符号,常用于表示快速、迅速或电) 异步/等待(Async/Await)全程高性能异步I/O
- 🎯 目标 简洁的API简洁直观的AI助手界面
- 🛡️ 译为中文是“盾牌”。这个符号通常用来表示防御、保护或安全的概念。 已准备好投入生产全面的错误处理和日志记录
📋 前提条件
- Python 3.10或更高版本
- Mem.ai API密钥(在这里获取一个)
🚀 快速入门
安装
- 克隆仓库:```bash
git clone https://github.com/yourusername/mcp-mem.ai.git
cd mcp-mem.ai
2. 安装依赖项:```bash
pip install -e .
- 设置您的环境:```bash
cp .env.example .env
Edit .env and add your MEM_API_KEY
### 运行服务器
#### 本地开发```bash
fastmcp run src/mcp_mem/server.py
与Claude Desktop配合使用
添加到您的Claude桌面配置中(claude_desktop_config.json):```json
{
"mcpServers": {
"mem": {
"command": "python",
"args": ["-m", "mcp_mem.server"],
"env": {
"MEM_API_KEY": "your_api_key_here"
}
}
}
}
#### 与其他MCP客户端配合使用```python
from mcp_mem import mcp
# Run the server
mcp.run()
🛠️ 可用工具
1. mem_it - 智能内容处理
使用AI驱动的组织功能,保存并自动处理任何内容类型。
参数:
input(必填):要保存的内容(文本、HTML、Markdown 等)instructions(可选):处理说明context(可选):为组织提供的额外背景信息timestamp(可选):ISO 8601 时间戳
示例:```python
mem_it(
input="Just had a great meeting with the product team about Q1 roadmap...",
instructions="Extract key action items and decisions",
context="Product Planning"
)
### 2. `create_note` - 创建结构化票据
创建一个Markdown格式的笔记,对内容和组织结构进行明确控制。
**参数:**
- `content` (必需):Markdown 格式的内容
- `collection_ids` (可选):集合 UUID 列表
- `collection_titles` (可选):收藏集标题列表
**示例:**```python
create_note(
content="""# Team Standup - Jan 15, 2024
## Completed
- Feature X shipped to production
- Bug fixes for issue #123
## In Progress
- Working on Feature Y
- Code review for PR #456
## Blockers
- Waiting for API access
""",
collection_titles=["Team Meetings", "Engineering"]
)
3. read_note - 阅读便签
通过ID检索笔记的完整内容和元数据。
参数:
note_id(必填):笔记的 UUID
示例:```python
read_note("01961d40-7a67-7049-a8a6-d5638cbaaeb9")
### 4. `delete_note` - 删除笔记
按ID永久删除一条笔记。
**参数:**
- `note_id` (必填):笔记的 UUID
**示例:**```python
delete_note("01961d40-7a67-7049-a8a6-d5638cbaaeb9")
5. create_collection - 创建收藏夹
创建一个新集合来整理相关笔记。
参数:
title(必填):集合标题description(可选):使用Markdown格式的描述
示例:```python
create_collection(
title="Project Apollo",
description="""# Project Apollo
All notes related to the Apollo project including:
- Meeting notes
- Technical specifications
- Customer feedback
"""
)
### 6. `delete_collection` - 删除集合
删除一个集合(笔记保留,只是不再关联)。
**参数:**
- `collection_id` (必填):集合的UUID
**示例:**```python
delete_collection("5e29c8a2-c73b-476b-9311-e2579712d4b1")
⚙️ 配置
配置是通过环境变量完成的。复制 .env.example to .env 并进行定制:```bash
Required: Your Mem.ai API key
MEM_API_KEY=your_api_key_here
Optional: Custom API endpoint (default: https://api.mem.ai/v2)
MEM_API_BASE_URL=https://api.mem.ai/v2
Optional: Request timeout in seconds (default: 30)
MEM_REQUEST_TIMEOUT=30
Optional: Enable debug logging (default: false)
MEM_DEBUG=false
## 🏗️ 建筑学```
src/mcp_mem/
├── __init__.py # Package initialization
├── models.py # Pydantic data models
├── client.py # Mem.ai API client
└── server.py # MCP server implementation
关键组件
models.py用于请求/响应验证的 Pydantic 模型client.pyMem.ai API的异步HTTP客户端封装server.py带有工具实现的FastMCP服务器
🧪 测试
运行测试套件:```bash
Install dev dependencies
pip install -e ".[dev]"
Run all tests
pytest
Run with coverage
pytest --cov=mcp_mem --cov-report=html
Run specific test file
pytest tests/test_client.py
## 🔍 错误处理
服务器提供了清晰、可操作的错误信息:
- `MemAuthenticationError`API密钥无效或缺失
- `MemNotFoundError`资源(笔记/集合)未找到
- `MemValidationError`无效的请求参数
- `MemAPIError`通用API错误
所有错误都会被记录下来,并连同有用的上下文信息一起返回给AI助手。
## 📚 示例
查看 `examples/` 完整使用示例目录:
- `basic_usage.py`每种工具的简单示例
- `advanced_usage.py`复杂的工作流程和模式
## 🤝 贡献
欢迎贡献!请随时提交拉取请求。
1. 为仓库创建分支(或:克隆仓库)
1. 创建你的特性分支(`git checkout -b feature/amazing-feature`)
1. 提交您的更改(`git commit -m 'Add amazing feature'`)
1. 推送至分支(`git push origin feature/amazing-feature`)
1. 提交一个拉取请求
## 📄 许可证
此项目遵循MIT许可证授权——详见 许可证 详情见文件。
## 🔗 链接
- Mem.ai API 文档
- 模型上下文协议
- FastMCP - MCP服务器框架
## 💡 应用场景
- **会议纪要**自动处理并整理会议记录
- **研究**保存并分类研究论文、文章和研究成果
- **客户反馈**收集并整理客户对话
- **知识库**构建一个可搜索的知识库
- **个人记忆**记录想法、思绪和所学
## 🐛 故障排除
### 认证错误```
MemAuthenticationError: MEM_API_KEY environment variable or api_key parameter is required
解决方案设定你的 MEM_API_KEY 在……中 .env 文件或环境。
连接超时```
httpx.ReadTimeout: timeout
**解决方案**增加 `MEM_REQUEST_TIMEOUT` 在你的 `.env` 文件。
### 无效的UUID```
MemValidationError: invalid UUID format
解决方案确保笔记/收藏ID是来自Mem.ai的有效UUID。
