README.md•7.7 kB
# MCP Server for Mem.ai
A production-ready Model Context Protocol (MCP) server that provides AI assistants with intelligent access to [Mem.ai](https://mem.ai)'s knowledge management platform.
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## ✨ Features
- 🧠 **Intelligent Memory**: Save and process content with Mem It's AI-powered organization
- 📝 **Note Management**: Create, read, and delete structured markdown notes
- 📁 **Collections**: Organize notes into searchable collections
- 🔒 **Type-Safe**: Full type hints and Pydantic validation
- ⚡ **Async/Await**: High-performance async I/O throughout
- 🎯 **Clean API**: Simple, intuitive interface for AI assistants
- 🛡️ **Production-Ready**: Comprehensive error handling and logging
- 🧪 **Well-Tested**: Full test suite with pytest
## 📋 Prerequisites
- Python 3.10 or higher
- A [Mem.ai](https://mem.ai) account
- Mem.ai API key ([get one here](https://mem.ai))
## 🚀 Quick Start
### Installation
1. Clone the repository:
```bash
git clone https://github.com/yourusername/mcp-mem.ai.git
cd mcp-mem.ai
```
2. Install dependencies:
```bash
pip install -e .
```
3. Set up your environment:
```bash
cp .env.example .env
# Edit .env and add your MEM_API_KEY
```
### Running the Server
#### Local Development
```bash
fastmcp run src/mcp_mem/server.py
```
#### Using with Claude Desktop
Add to your Claude Desktop configuration (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"mem": {
"command": "python",
"args": ["-m", "mcp_mem.server"],
"env": {
"MEM_API_KEY": "your_api_key_here"
}
}
}
}
```
#### Using with Other MCP Clients
```python
from mcp_mem import mcp
# Run the server
mcp.run()
```
## 🛠️ Available Tools
### 1. `mem_it` - Intelligent Content Processing
Save and automatically process any content type with AI-powered organization.
**Parameters:**
- `input` (required): Content to save (text, HTML, markdown, etc.)
- `instructions` (optional): Processing instructions
- `context` (optional): Additional context for organization
- `timestamp` (optional): ISO 8601 timestamp
**Example:**
```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` - Create Structured Note
Create a markdown-formatted note with explicit control over content and organization.
**Parameters:**
- `content` (required): Markdown-formatted content
- `collection_ids` (optional): List of collection UUIDs
- `collection_titles` (optional): List of collection titles
**Example:**
```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` - Read Note
Retrieve a note's full content and metadata by ID.
**Parameters:**
- `note_id` (required): UUID of the note
**Example:**
```python
read_note("01961d40-7a67-7049-a8a6-d5638cbaaeb9")
```
### 4. `delete_note` - Delete Note
Permanently delete a note by ID.
**Parameters:**
- `note_id` (required): UUID of the note
**Example:**
```python
delete_note("01961d40-7a67-7049-a8a6-d5638cbaaeb9")
```
### 5. `create_collection` - Create Collection
Create a new collection to organize related notes.
**Parameters:**
- `title` (required): Collection title
- `description` (optional): Markdown-formatted description
**Example:**
```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` - Delete Collection
Delete a collection (notes remain, just unassociated).
**Parameters:**
- `collection_id` (required): UUID of the collection
**Example:**
```python
delete_collection("5e29c8a2-c73b-476b-9311-e2579712d4b1")
```
## ⚙️ Configuration
Configuration is done via environment variables. Copy `.env.example` to `.env` and customize:
```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
```
## 🏗️ Architecture
```
src/mcp_mem/
├── __init__.py # Package initialization
├── models.py # Pydantic data models
├── client.py # Mem.ai API client
└── server.py # MCP server implementation
```
### Key Components
- **`models.py`**: Pydantic models for request/response validation
- **`client.py`**: Async HTTP client wrapper for Mem.ai API
- **`server.py`**: FastMCP server with tool implementations
## 🧪 Testing
Run the test suite:
```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
```
## 🔍 Error Handling
The server provides clear, actionable error messages:
- `MemAuthenticationError`: Invalid or missing API key
- `MemNotFoundError`: Resource (note/collection) not found
- `MemValidationError`: Invalid request parameters
- `MemAPIError`: General API errors
All errors are logged and returned with helpful context to the AI assistant.
## 📚 Examples
See the `examples/` directory for complete usage examples:
- `basic_usage.py`: Simple examples of each tool
- `advanced_usage.py`: Complex workflows and patterns
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- [Mem.ai](https://mem.ai) - Intelligent memory platform
- [Mem.ai API Documentation](https://docs.mem.ai)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
## 💡 Use Cases
- **Meeting Notes**: Automatically process and organize meeting transcripts
- **Research**: Save and categorize research papers, articles, and findings
- **Customer Feedback**: Collect and organize customer conversations
- **Knowledge Base**: Build a searchable knowledge repository
- **Personal Memory**: Keep track of ideas, thoughts, and learnings
## 🐛 Troubleshooting
### Authentication Error
```
MemAuthenticationError: MEM_API_KEY environment variable or api_key parameter is required
```
**Solution**: Set your `MEM_API_KEY` in the `.env` file or environment.
### Connection Timeout
```
httpx.ReadTimeout: timeout
```
**Solution**: Increase `MEM_REQUEST_TIMEOUT` in your `.env` file.
### Invalid UUID
```
MemValidationError: invalid UUID format
```
**Solution**: Ensure note/collection IDs are valid UUIDs from Mem.ai.
---
Built with ❤️ using [FastMCP](https://github.com/jlowin/fastmcp) and [Mem.ai](https://mem.ai)