https://github.com/evgenygurin/vercel-mcp-memory
Semantic memory server for Claude AI with OpenAI embeddings and PostgreSQL pgvector. Deploy on Vercel Edge Functions with zero infrastructure.
https://github.com/evgenygurin/vercel-mcp-memory
ai claude edge-functions embeddings mcp memory-server nextjs openai pgvector postgresql semantic-search typescript vercel
Last synced: 2 months ago
JSON representation
Semantic memory server for Claude AI with OpenAI embeddings and PostgreSQL pgvector. Deploy on Vercel Edge Functions with zero infrastructure.
- Host: GitHub
- URL: https://github.com/evgenygurin/vercel-mcp-memory
- Owner: evgenygurin
- License: mit
- Created: 2025-11-07T17:21:40.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-11-07T19:10:29.000Z (7 months ago)
- Last Synced: 2025-11-07T19:20:15.022Z (7 months ago)
- Topics: ai, claude, edge-functions, embeddings, mcp, memory-server, nextjs, openai, pgvector, postgresql, semantic-search, typescript, vercel
- Language: TypeScript
- Homepage: https://vercel-mcp-memory.vercel.app
- Size: 94.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# Vercel MCP Memory
[](https://github.com/evgenygurin/vercel-mcp-memory/actions/workflows/ci.yml)
[](https://github.com/evgenygurin/vercel-mcp-memory/actions/workflows/codeql.yml)
[](https://docs.claude.com/en/docs/claude-code)
[](https://opensource.org/licenses/MIT)
[](https://github.com/evgenygurin/vercel-mcp-memory/issues)
[](https://github.com/evgenygurin/vercel-mcp-memory/stargazers)
Custom Model Context Protocol (MCP) memory server deployed on Vercel with semantic search powered by OpenAI embeddings and PostgreSQL pgvector.
## ✨ Features
- 🧠 **Semantic Search** - Find memories by meaning, not just keywords
- 🔐 **Secure API** - Optional API key authentication for production
- ☁️ **Cloud-Hosted** - Deployed on Vercel Edge Functions (zero-infrastructure)
- 🔄 **Cross-Device Sync** - Access your memory from any device with Claude
- 🚀 **OpenAI Embeddings** - Using text-embedding-3-small model
- 🗄️ **PostgreSQL + pgvector** - Efficient vector similarity search
- ✅ **Input Validation** - Zod schemas for robust data validation
- 📝 **Structured Logging** - Production-ready error tracking
- 🌍 **Multi-language** - Supports Russian, English and more
- 🤖 **Claude Code Integration** - Automated PR reviews and AI assistant via GitHub Actions
## 🏗️ Architecture
```text
Claude Desktop → HTTPS/JSON-RPC → Vercel Edge Function → Postgres (pgvector)
↓
OpenAI Embeddings API
```
## 📋 Prerequisites
- Node.js 20.x
- Vercel account (free tier works)
- OpenAI API key (for embeddings, ~$0.10/1M tokens)
- PostgreSQL database with pgvector extension (Vercel Postgres or Neon)
## 🚀 Quick Start
### 1. Install Dependencies
```bash
cd vercel-mcp-memory
npm install
```
### 2. Set Up Vercel Postgres
```bash
# Install Vercel CLI
npm i -g vercel
# Login to Vercel
vercel login
# Link project
vercel link
# Create Postgres database (via Vercel Dashboard)
# 1. Go to https://vercel.com/dashboard
# 2. Navigate to Storage → Create Database → Postgres
# 3. Name: mcp-memory-db
# 4. Region: Select closest to you
```
### 3. Configure Environment Variables
Create `.env.local` file:
```bash
# Required: OpenAI API key for embeddings
OPENAI_API_KEY=sk-...
# Required: PostgreSQL connection (auto-configured by Vercel)
POSTGRES_URL=postgresql://...
# Optional: API keys for authentication (comma-separated)
# Leave empty for development without auth
MCP_API_KEYS=your-secret-key-1,your-secret-key-2
```
Generate secure API keys:
```bash
# Generate a secure API key
openssl rand -base64 32
```
### 4. Run Database Migration
Apply the SQL schema with pgvector extension:
```bash
# Option 1: Via Vercel Dashboard
# 1. Go to Storage → mcp-memory-db → SQL Editor
# 2. Copy contents of migrations/001_init.sql
# 3. Execute
# Option 2: Via psql (if you have local connection)
psql $POSTGRES_URL < migrations/001_init.sql
```
### 5. Deploy to Vercel
```bash
vercel --prod
```
Your MCP server will be available at: `https://your-project.vercel.app`
### 6. Configure Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/claude-desktop/claude_desktop_config.json` (Linux):
**With authentication (recommended for production):**
```json
{
"mcpServers": {
"vercel-memory": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://your-project.vercel.app/api/mcp/sse"
],
"env": {
"MCP_API_KEY": "your-secret-key-here"
}
}
}
}
```
**Without authentication (development only):**
```json
{
"mcpServers": {
"vercel-memory": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://your-project.vercel.app/api/mcp/sse"
]
}
}
}
```
Restart Claude Desktop.
## 🧪 Testing
### Health Check
```bash
curl https://your-project.vercel.app/api/health
```
Should return:
```json
{
"status": "healthy",
"service": "vercel-mcp-memory",
"database": {
"connected": true
}
}
```
### Test MCP Endpoint with Authentication
```bash
curl -X POST https://your-project.vercel.app/api/mcp/sse \
-H "Content-Type: application/json" \
-H "X-API-Key: your-secret-key" \
-d '{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}'
```
### Test in Claude
```bash
User: Remember: I prefer Python for backend development
Claude: [Uses add_memory tool]
User: What programming languages do I prefer?
Claude: [Uses search_memory tool and finds "Python"]
```
## 📊 MCP Tools
### `add_memory`
Store new memory with semantic embeddings.
```typescript
{
content: string, // Required (1-10000 chars)
category?: string, // Optional (max 100 chars)
metadata?: object // Optional custom key-value pairs
}
```
### `search_memory`
Semantic search across memories.
```typescript
{
query: string, // Required: natural language query (1-1000 chars)
category?: string, // Filter by category
limit?: number, // Max results (default: 10, max: 50)
threshold?: number // Min similarity 0-1 (default: 0.5)
}
```
### `list_memories`
List all memories chronologically.
```typescript
{
category?: string, // Filter by category
limit?: number, // Max results (default: 50, max: 100)
offset?: number // Pagination offset (default: 0)
}
```
### `delete_memory`
Delete specific memory by UUID.
```typescript
{
id: string // UUID of memory (validated)
}
```
### `memory_stats`
Get statistics about stored memories.
```typescript
{} // No parameters
```
## 📁 Project Structure
```text
vercel-mcp-memory/
├── app/
│ ├── api/
│ │ ├── health/route.ts # Health check endpoint
│ │ └── mcp/sse/route.ts # MCP JSON-RPC endpoint
│ ├── layout.tsx # Next.js layout
│ └── page.tsx # Landing page
├── lib/
│ ├── auth.ts # API authentication
│ ├── db.ts # Postgres + pgvector queries
│ ├── embeddings.ts # OpenAI embeddings client
│ ├── logger.ts # Structured logging
│ ├── mcp-handlers.ts # Centralized tool handlers
│ ├── mcp-server.ts # MCP SDK integration
│ ├── types.ts # TypeScript definitions
│ └── validation.ts # Zod input validation
├── migrations/
│ └── 001_init.sql # Database schema
├── scripts/
│ ├── insert-test-data.ts # Test data seeding
│ └── migrate-old-data.ts # Legacy data migration
├── .env.example # Environment variables template
├── .eslintrc.json # ESLint configuration
├── .gitignore # Git ignore rules
├── SECURITY.md # Security guidelines
├── next.config.js # Next.js configuration
├── package.json # Dependencies
├── tsconfig.json # TypeScript configuration
└── vercel.json # Vercel deployment config
```
## 🔧 Development
```bash
# Run locally
npm run dev
# Build for production
npm run build
# Lint code
npm run lint
# Migrate old data
npm run migrate
```
## 🔐 Security
See [SECURITY.md](./SECURITY.md) for security best practices.
**Important:**
- Never commit `.env.local` or `.env.production` files
- Rotate API keys regularly
- Enable `MCP_API_KEYS` authentication in production
- Monitor API usage to prevent quota exhaustion
- Review [SECURITY.md](./SECURITY.md) before deploying
## 💰 Cost Estimation
**Vercel Free Tier (sufficient for personal use):**
- ✅ Functions: 100 GB-hours/month
- ✅ Postgres: 256 MB storage
- ✅ Bandwidth: 100 GB
**After free tier:**
- Postgres: ~$0.20/GB/month
- OpenAI Embeddings: ~$0.10/1M tokens (~$0.02/month for typical usage)
- Functions: ~$40/100 GB-hours
**Expected cost**: $0-5/month for moderate personal use.
## 🐛 Troubleshooting
### Claude can't connect
1. Check health endpoint: `curl https://your-project.vercel.app/api/health`
2. Verify API key matches in both Vercel env and Claude config
3. Check Vercel deployment: `vercel ls`
4. Verify Claude config path is correct
5. Restart Claude Desktop
### Authentication errors
1. Verify `MCP_API_KEYS` is set in Vercel environment variables
2. Check API key format (no extra spaces or newlines)
3. Ensure Claude config includes `MCP_API_KEY` in env section
4. Try without authentication first (remove `MCP_API_KEYS` from Vercel env)
### Database errors
1. Verify pgvector extension is enabled:
```sql
SELECT * FROM pg_extension WHERE extname = 'vector';
```
2. Check table exists:
```sql
\dt memories
```
3. View connection logs in Vercel Dashboard → Functions → Logs
### Embedding errors
1. Verify OpenAI API key is set: `vercel env ls`
2. Check API key has sufficient credits
3. Monitor usage:
## 📖 Resources
- [Vercel Documentation](https://vercel.com/docs)
- [MCP Specification](https://modelcontextprotocol.io)
- [OpenAI Embeddings](https://platform.openai.com/docs/guides/embeddings)
- [pgvector](https://github.com/pgvector/pgvector)
## 🤖 Claude Code Integration
This repository uses Claude Code via GitHub Actions for automated code reviews and AI assistance.
### Automated PR Reviews
Every pull request automatically receives a comprehensive code review from Claude, focusing on:
- Code quality and best practices
- Potential bugs and security issues
- Performance considerations
- Test coverage
### Interactive AI Assistant
Mention `@claude` in any issue or PR comment to get help:
```bash
@claude Please review the security implications of these auth changes.
@claude Help me fix the TypeScript errors in lib/db.ts.
@claude Update CLAUDE.md to reflect the new architecture.
```
For detailed setup and troubleshooting, see [.github/CLAUDE_CODE_SETUP.md](.github/CLAUDE_CODE_SETUP.md).
## 📝 License
MIT
## 🤝 Contributing
Contributions are welcome! Please read our [Contributing Guidelines](.github/CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) first.
Quick steps:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
For questions or support, see [SUPPORT.md](SUPPORT.md).
## 🙏 Acknowledgments
Built with:
- [Vercel](https://vercel.com) - Hosting and Postgres
- [Next.js](https://nextjs.org) - React framework
- [OpenAI](https://openai.com) - Embeddings API
- [MCP SDK](https://github.com/modelcontextprotocol/sdk) - Protocol implementation
- [pgvector](https://github.com/pgvector/pgvector) - Vector similarity search
---
Made with ❤️ using Vercel, Next.js, and Claude Code