vercel-mcp-memory

evgenygurin/vercel-mcp-memory

3.2

If you are the rightful owner of vercel-mcp-memory and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Vercel MCP Memory is a custom Model Context Protocol (MCP) memory server that leverages semantic search capabilities using OpenAI embeddings and PostgreSQL pgvector, deployed on Vercel.

Tools
5
Resources
0
Prompts
0

Vercel MCP Memory

CI CodeQL Claude Code License: MIT GitHub issues GitHub stars

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

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

cd vercel-mcp-memory
npm install

2. Set Up Vercel Postgres

# 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:

# 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:

# Generate a secure API key
openssl rand -base64 32

4. Run Database Migration

Apply the SQL schema with pgvector extension:

# 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

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):

{
  "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):

{
  "mcpServers": {
    "vercel-memory": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-project.vercel.app/api/mcp/sse"
      ]
    }
  }
}

Restart Claude Desktop.

🧪 Testing

Health Check

curl https://your-project.vercel.app/api/health

Should return:

{
  "status": "healthy",
  "service": "vercel-mcp-memory",
  "database": {
    "connected": true
  }
}

Test MCP Endpoint with Authentication

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

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.

{
  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.

{
  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.

{
  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.

{
  id: string           // UUID of memory (validated)
}

memory_stats

Get statistics about stored memories.

{}  // No parameters

📁 Project Structure

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

# Run locally
npm run dev

# Build for production
npm run build

# Lint code
npm run lint

# Migrate old data
npm run migrate

🔐 Security

See 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 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:

    SELECT * FROM pg_extension WHERE extname = 'vector';

  2. Check table exists:

    \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: https://platform.openai.com/usage

📖 Resources

🤖 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:

@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 .

📝 License

MIT

🤝 Contributing

Contributions are welcome! Please read our and 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 .

🙏 Acknowledgments

Built with:

Made with ❤️ using Vercel, Next.js, and Claude Code