# Mem-Brain MCP Server

MCP (Model Context Protocol) server that exposes Mem-Brain API functionality as standardized tools for AI agents. Built with [FastMCP](https://gofastmcp.com) for production-ready HTTP/SSE transport.

## Features

- **Memory Management**: Create, read, update, and delete memories
- **Semantic Search**: Search memories using vector similarity
- **Graph Operations**: Find paths and neighborhoods in the memory graph
- **Statistics**: Get insights about your memory system
- **Link Management**: Link and unlink memories
- **HTTP/SSE Transport**: Run independently, accessible remotely
- **CLI Interface**: Packaged for easy global execution

## Instant Execution (Recommended)

You can run the MCP server instantly without manual installation using `uv`:

```bash
# Run using uvx (loads environment from .env or shell)
uvx mem-brain-mcp

# Run with custom API URL
export API_BASE_URL=http://your-api-alb-url.com
uvx mem-brain-mcp
```

## Installation

### From Source

1. Install using `uv` (recommended) or `pip`:

```bash
cd mem-brain-mcp
uv pip install .
```

2. Run globally:

```bash
mem-brain-mcp
```

## Configuration

The server reads configuration from environment variables or a `.env` file in the current working directory:

```env
# API Configuration
API_BASE_URL=http://localhost:8000
# NOTE: API_KEY is optional here - per-user API keys are configured in MCP clients
API_KEY=your_api_key_here  # Optional: fallback for single-user scenarios

# MCP Server Configuration
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8100

# Logging
LOG_LEVEL=INFO
```

## Per-User API Key Configuration

Each user must configure their own API key in their MCP client for proper user isolation. The server extracts tokens from request headers.

### Cursor IDE (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mem-brain": {
      "url": "http://localhost:8100/mcp",
      "headers": {
        "Authorization": "Bearer your-jwt-token"
      }
    }
  }
}
```

### Claude Desktop

#### Option 1: Native Remote (Pro/Team plans)
Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "mem-brain": {
      "url": "http://your-deployed-url/mcp",
      "headers": {
        "Authorization": "Bearer your-jwt-token"
      }
    }
  }
}
```

#### Option 2: via CLI (Any plan)
```json
{
  "mcpServers": {
    "mem-brain": {
      "command": "uvx",
      "args": ["mem-brain-mcp"],
      "env": {
        "API_BASE_URL": "http://your-deployed-url",
        "JWT_SECRET_KEY": "your-secret"
      }
    }
  }
}
```

## AWS ECS Deployment

The MCP server can be deployed to AWS ECS (Fargate) with an Application Load Balancer.

### Quick Start

1. **Set up security groups** (see [aws/security-groups.md](./aws/security-groups.md))
2. **Deploy using the script:**

```bash
cd mem-brain-mcp/aws
./deploy.sh ap-south-1 membrain-mcp membrain-cluster membrain-mcp
```

For detailed instructions, see [aws/DEPLOYMENT.md](./aws/DEPLOYMENT.md).

## Development

### Running Tests
```bash
pytest
```

### Build and Publish
```bash
# Build the wheel
python3 -m build

# Upload to PyPI
twine upload dist/*
```

## License

Same as Mem-Brain API project.
