PostgreSQL-based memory system with vector search capabilities for AI applications, including MCP integration for Claude.
This package provides a memory system built on PostgreSQL with pgvector that enables:
- Storage and retrieval of vectorized content for semantic search
- Persistent memory across sessions
- Integration with Claude through the Model Context Protocol (MCP)
- Support for multiple embedding models (OpenAI, Anthropic, or mock for testing)
npm install -g postgres-mcp-toolsFor detailed installation instructions including troubleshooting, see INSTALLATION.md.
# Start PostgreSQL in Docker
docker-compose up -d postgres# Start the MCP server
docker-compose up -d mcp-server# Verify the robust transport functionality
npm run test-transportSee CLAUDE_DESKTOP_SETUP.md for detailed instructions.
- Vector Search: Store and search content using vector embeddings
- Multiple Embedding Models: Support for OpenAI, Anthropic, or mock embeddings
- MCP Integration: Connect directly to Claude via the Model Context Protocol
- REST API: Access memory programmatically through HTTP endpoints
- Docker Support: Run everything in containers for easy deployment
Configuration is managed through environment variables or command-line arguments:
-
POSTGRES_HOST: PostgreSQL host (default: localhost) -
POSTGRES_PORT: PostgreSQL port (default: 5432) -
POSTGRES_USER: PostgreSQL username (default: memory_user) -
POSTGRES_PASSWORD: PostgreSQL password -
POSTGRES_DB: PostgreSQL database name (default: memory_db) -
EMBEDDING_MODEL: Embedding model to use: "openai", "anthropic", or "mock" (default: mock) -
OPENAI_API_KEY: OpenAI API key (if using OpenAI embeddings) -
ANTHROPIC_API_KEY: Anthropic API key (if using Anthropic embeddings) -
MCP_SERVER_PORT: MCP server port (default: 3000) -
HTTP_PORT: HTTP API port (default: 8080)
The easiest way to run PostgreSQL MCP Tools is using Docker:
# Start everything
docker-compose up -d
# Stop everything
docker-compose down# Install dependencies
npm install
# Install test dependencies
npm run update-deps
# Build the server
npm run build-server
# Run minimal tests (recommended)
npm run test:basic
# Run transport tests (may require configuration)
npm run test:transportNote: The test setup is configured for ESM compatibility in a primarily ESM project. If you encounter issues, try the alternate test configuration with
npm run test:alt.
See tests/README.md for more information on testing.
As of version 1.0.9, PostgreSQL MCP Tools now properly integrates with Claude Desktop by ensuring all debug logs go to stderr instead of stdout, maintaining proper JSON-RPC protocol communication.
We've implemented a production-ready robust transport layer that handles non-JSON messages gracefully. This fixes issues where plain text log messages were causing the server to crash with JSON parsing errors.
Key improvements:
- Added error handling for non-JSON messages in the transport layer
- Implemented a robust HTTP transport that doesn't crash on invalid input
- Added global error handlers to prevent unhandled exceptions and rejections
- Improved logging to help diagnose issues
- Properly handles bidirectional communication with clients
- Maintains session information required by the MCP protocol
- Updated Claude Desktop configuration format for proper port settings
For detailed information about the robust transport implementation, see ROBUST_TRANSPORT.md.
If you previously experienced JSON parsing errors when starting the server, this update should resolve those issues.
See full RELEASE_NOTES.md for all changes.
If you're upgrading from a previous version, run:
npm update -g postgres-mcp-toolsThen update your Claude Desktop configuration as described in CLAUDE_DESKTOP_SETUP.md and restart the MCP server:
npm run start-serverMIT