{"id":32873112,"url":"https://github.com/evgenygurin/vercel-mcp-memory","last_synced_at":"2026-04-08T23:34:14.231Z","repository":{"id":323039544,"uuid":"1091896071","full_name":"evgenygurin/vercel-mcp-memory","owner":"evgenygurin","description":"Semantic memory server for Claude AI with OpenAI embeddings and PostgreSQL pgvector. Deploy on Vercel Edge Functions with zero infrastructure.","archived":false,"fork":false,"pushed_at":"2025-11-07T19:10:29.000Z","size":97,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-07T19:20:15.022Z","etag":null,"topics":["ai","claude","edge-functions","embeddings","mcp","memory-server","nextjs","openai","pgvector","postgresql","semantic-search","typescript","vercel"],"latest_commit_sha":null,"homepage":"https://vercel-mcp-memory.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evgenygurin.png","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","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-11-07T17:21:40.000Z","updated_at":"2025-11-07T19:10:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/evgenygurin/vercel-mcp-memory","commit_stats":null,"previous_names":["evgenygurin/vercel-mcp-memory"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/evgenygurin/vercel-mcp-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenygurin%2Fvercel-mcp-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenygurin%2Fvercel-mcp-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenygurin%2Fvercel-mcp-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenygurin%2Fvercel-mcp-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evgenygurin","download_url":"https://codeload.github.com/evgenygurin/vercel-mcp-memory/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenygurin%2Fvercel-mcp-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31579056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","edge-functions","embeddings","mcp","memory-server","nextjs","openai","pgvector","postgresql","semantic-search","typescript","vercel"],"created_at":"2025-11-09T14:00:33.713Z","updated_at":"2026-04-08T23:34:14.226Z","avatar_url":"https://github.com/evgenygurin.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vercel MCP Memory\n\n[![CI](https://github.com/evgenygurin/vercel-mcp-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/evgenygurin/vercel-mcp-memory/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/evgenygurin/vercel-mcp-memory/actions/workflows/codeql.yml/badge.svg)](https://github.com/evgenygurin/vercel-mcp-memory/actions/workflows/codeql.yml)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-Enabled-7C3AED?logo=anthropic)](https://docs.claude.com/en/docs/claude-code)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub issues](https://img.shields.io/github/issues/evgenygurin/vercel-mcp-memory)](https://github.com/evgenygurin/vercel-mcp-memory/issues)\n[![GitHub stars](https://img.shields.io/github/stars/evgenygurin/vercel-mcp-memory)](https://github.com/evgenygurin/vercel-mcp-memory/stargazers)\n\nCustom Model Context Protocol (MCP) memory server deployed on Vercel with semantic search powered by OpenAI embeddings and PostgreSQL pgvector.\n\n## ✨ Features\n\n- 🧠 **Semantic Search** - Find memories by meaning, not just keywords\n- 🔐 **Secure API** - Optional API key authentication for production\n- ☁️ **Cloud-Hosted** - Deployed on Vercel Edge Functions (zero-infrastructure)\n- 🔄 **Cross-Device Sync** - Access your memory from any device with Claude\n- 🚀 **OpenAI Embeddings** - Using text-embedding-3-small model\n- 🗄️ **PostgreSQL + pgvector** - Efficient vector similarity search\n- ✅ **Input Validation** - Zod schemas for robust data validation\n- 📝 **Structured Logging** - Production-ready error tracking\n- 🌍 **Multi-language** - Supports Russian, English and more\n- 🤖 **Claude Code Integration** - Automated PR reviews and AI assistant via GitHub Actions\n\n## 🏗️ Architecture\n\n```text\nClaude Desktop → HTTPS/JSON-RPC → Vercel Edge Function → Postgres (pgvector)\n                                         ↓\n                                   OpenAI Embeddings API\n```\n\n## 📋 Prerequisites\n\n- Node.js 20.x\n- Vercel account (free tier works)\n- OpenAI API key (for embeddings, ~$0.10/1M tokens)\n- PostgreSQL database with pgvector extension (Vercel Postgres or Neon)\n\n## 🚀 Quick Start\n\n### 1. Install Dependencies\n\n```bash\ncd vercel-mcp-memory\nnpm install\n```\n\n### 2. Set Up Vercel Postgres\n\n```bash\n# Install Vercel CLI\nnpm i -g vercel\n\n# Login to Vercel\nvercel login\n\n# Link project\nvercel link\n\n# Create Postgres database (via Vercel Dashboard)\n# 1. Go to https://vercel.com/dashboard\n# 2. Navigate to Storage → Create Database → Postgres\n# 3. Name: mcp-memory-db\n# 4. Region: Select closest to you\n```\n\n### 3. Configure Environment Variables\n\nCreate `.env.local` file:\n\n```bash\n# Required: OpenAI API key for embeddings\nOPENAI_API_KEY=sk-...\n\n# Required: PostgreSQL connection (auto-configured by Vercel)\nPOSTGRES_URL=postgresql://...\n\n# Optional: API keys for authentication (comma-separated)\n# Leave empty for development without auth\nMCP_API_KEYS=your-secret-key-1,your-secret-key-2\n```\n\nGenerate secure API keys:\n\n```bash\n# Generate a secure API key\nopenssl rand -base64 32\n```\n\n### 4. Run Database Migration\n\nApply the SQL schema with pgvector extension:\n\n```bash\n# Option 1: Via Vercel Dashboard\n# 1. Go to Storage → mcp-memory-db → SQL Editor\n# 2. Copy contents of migrations/001_init.sql\n# 3. Execute\n\n# Option 2: Via psql (if you have local connection)\npsql $POSTGRES_URL \u003c migrations/001_init.sql\n```\n\n### 5. Deploy to Vercel\n\n```bash\nvercel --prod\n```\n\nYour MCP server will be available at: `https://your-project.vercel.app`\n\n### 6. Configure Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/claude-desktop/claude_desktop_config.json` (Linux):\n\n**With authentication (recommended for production):**\n\n```json\n{\n  \"mcpServers\": {\n    \"vercel-memory\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://your-project.vercel.app/api/mcp/sse\"\n      ],\n      \"env\": {\n        \"MCP_API_KEY\": \"your-secret-key-here\"\n      }\n    }\n  }\n}\n```\n\n**Without authentication (development only):**\n\n```json\n{\n  \"mcpServers\": {\n    \"vercel-memory\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://your-project.vercel.app/api/mcp/sse\"\n      ]\n    }\n  }\n}\n```\n\nRestart Claude Desktop.\n\n## 🧪 Testing\n\n### Health Check\n\n```bash\ncurl https://your-project.vercel.app/api/health\n```\n\nShould return:\n\n```json\n{\n  \"status\": \"healthy\",\n  \"service\": \"vercel-mcp-memory\",\n  \"database\": {\n    \"connected\": true\n  }\n}\n```\n\n### Test MCP Endpoint with Authentication\n\n```bash\ncurl -X POST https://your-project.vercel.app/api/mcp/sse \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: your-secret-key\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"method\": \"tools/list\",\n    \"id\": 1\n  }'\n```\n\n### Test in Claude\n\n```bash\nUser: Remember: I prefer Python for backend development\nClaude: [Uses add_memory tool]\n\nUser: What programming languages do I prefer?\nClaude: [Uses search_memory tool and finds \"Python\"]\n```\n\n## 📊 MCP Tools\n\n### `add_memory`\n\nStore new memory with semantic embeddings.\n\n```typescript\n{\n  content: string,      // Required (1-10000 chars)\n  category?: string,    // Optional (max 100 chars)\n  metadata?: object     // Optional custom key-value pairs\n}\n```\n\n### `search_memory`\n\nSemantic search across memories.\n\n```typescript\n{\n  query: string,        // Required: natural language query (1-1000 chars)\n  category?: string,    // Filter by category\n  limit?: number,       // Max results (default: 10, max: 50)\n  threshold?: number    // Min similarity 0-1 (default: 0.5)\n}\n```\n\n### `list_memories`\n\nList all memories chronologically.\n\n```typescript\n{\n  category?: string,    // Filter by category\n  limit?: number,       // Max results (default: 50, max: 100)\n  offset?: number       // Pagination offset (default: 0)\n}\n```\n\n### `delete_memory`\n\nDelete specific memory by UUID.\n\n```typescript\n{\n  id: string           // UUID of memory (validated)\n}\n```\n\n### `memory_stats`\n\nGet statistics about stored memories.\n\n```typescript\n{}  // No parameters\n```\n\n## 📁 Project Structure\n\n```text\nvercel-mcp-memory/\n├── app/\n│   ├── api/\n│   │   ├── health/route.ts          # Health check endpoint\n│   │   └── mcp/sse/route.ts         # MCP JSON-RPC endpoint\n│   ├── layout.tsx                   # Next.js layout\n│   └── page.tsx                     # Landing page\n├── lib/\n│   ├── auth.ts                      # API authentication\n│   ├── db.ts                        # Postgres + pgvector queries\n│   ├── embeddings.ts                # OpenAI embeddings client\n│   ├── logger.ts                    # Structured logging\n│   ├── mcp-handlers.ts              # Centralized tool handlers\n│   ├── mcp-server.ts                # MCP SDK integration\n│   ├── types.ts                     # TypeScript definitions\n│   └── validation.ts                # Zod input validation\n├── migrations/\n│   └── 001_init.sql                 # Database schema\n├── scripts/\n│   ├── insert-test-data.ts          # Test data seeding\n│   └── migrate-old-data.ts          # Legacy data migration\n├── .env.example                     # Environment variables template\n├── .eslintrc.json                   # ESLint configuration\n├── .gitignore                       # Git ignore rules\n├── SECURITY.md                      # Security guidelines\n├── next.config.js                   # Next.js configuration\n├── package.json                     # Dependencies\n├── tsconfig.json                    # TypeScript configuration\n└── vercel.json                      # Vercel deployment config\n```\n\n## 🔧 Development\n\n```bash\n# Run locally\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Lint code\nnpm run lint\n\n# Migrate old data\nnpm run migrate\n```\n\n## 🔐 Security\n\nSee [SECURITY.md](./SECURITY.md) for security best practices.\n\n**Important:**\n\n- Never commit `.env.local` or `.env.production` files\n- Rotate API keys regularly\n- Enable `MCP_API_KEYS` authentication in production\n- Monitor API usage to prevent quota exhaustion\n- Review [SECURITY.md](./SECURITY.md) before deploying\n\n## 💰 Cost Estimation\n\n**Vercel Free Tier (sufficient for personal use):**\n\n- ✅ Functions: 100 GB-hours/month\n- ✅ Postgres: 256 MB storage\n- ✅ Bandwidth: 100 GB\n\n**After free tier:**\n\n- Postgres: ~$0.20/GB/month\n- OpenAI Embeddings: ~$0.10/1M tokens (~$0.02/month for typical usage)\n- Functions: ~$40/100 GB-hours\n\n**Expected cost**: $0-5/month for moderate personal use.\n\n## 🐛 Troubleshooting\n\n### Claude can't connect\n\n1. Check health endpoint: `curl https://your-project.vercel.app/api/health`\n2. Verify API key matches in both Vercel env and Claude config\n3. Check Vercel deployment: `vercel ls`\n4. Verify Claude config path is correct\n5. Restart Claude Desktop\n\n### Authentication errors\n\n1. Verify `MCP_API_KEYS` is set in Vercel environment variables\n2. Check API key format (no extra spaces or newlines)\n3. Ensure Claude config includes `MCP_API_KEY` in env section\n4. Try without authentication first (remove `MCP_API_KEYS` from Vercel env)\n\n### Database errors\n\n1. Verify pgvector extension is enabled:\n\n   ```sql\n   SELECT * FROM pg_extension WHERE extname = 'vector';\n   ```\n\n2. Check table exists:\n\n   ```sql\n   \\dt memories\n   ```\n\n3. View connection logs in Vercel Dashboard → Functions → Logs\n\n### Embedding errors\n\n1. Verify OpenAI API key is set: `vercel env ls`\n2. Check API key has sufficient credits\n3. Monitor usage: \u003chttps://platform.openai.com/usage\u003e\n\n## 📖 Resources\n\n- [Vercel Documentation](https://vercel.com/docs)\n- [MCP Specification](https://modelcontextprotocol.io)\n- [OpenAI Embeddings](https://platform.openai.com/docs/guides/embeddings)\n- [pgvector](https://github.com/pgvector/pgvector)\n\n## 🤖 Claude Code Integration\n\nThis repository uses Claude Code via GitHub Actions for automated code reviews and AI assistance.\n\n### Automated PR Reviews\n\nEvery pull request automatically receives a comprehensive code review from Claude, focusing on:\n- Code quality and best practices\n- Potential bugs and security issues\n- Performance considerations\n- Test coverage\n\n### Interactive AI Assistant\n\nMention `@claude` in any issue or PR comment to get help:\n\n```bash\n@claude Please review the security implications of these auth changes.\n@claude Help me fix the TypeScript errors in lib/db.ts.\n@claude Update CLAUDE.md to reflect the new architecture.\n```\n\nFor detailed setup and troubleshooting, see [.github/CLAUDE_CODE_SETUP.md](.github/CLAUDE_CODE_SETUP.md).\n\n## 📝 License\n\nMIT\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](.github/CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) first.\n\nQuick steps:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\nFor questions or support, see [SUPPORT.md](SUPPORT.md).\n\n## 🙏 Acknowledgments\n\nBuilt with:\n\n- [Vercel](https://vercel.com) - Hosting and Postgres\n- [Next.js](https://nextjs.org) - React framework\n- [OpenAI](https://openai.com) - Embeddings API\n- [MCP SDK](https://github.com/modelcontextprotocol/sdk) - Protocol implementation\n- [pgvector](https://github.com/pgvector/pgvector) - Vector similarity search\n\n---\n\nMade with ❤️ using Vercel, Next.js, and Claude Code\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevgenygurin%2Fvercel-mcp-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevgenygurin%2Fvercel-mcp-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevgenygurin%2Fvercel-mcp-memory/lists"}