Overmind PostgreSQL MCP Server

1.2.0 verified Sat May 09 auth: no javascript

A comprehensive MCP server for PostgreSQL database interaction, integrating semantic intelligence via embeddings and RAG (Retrieval-Augmented Generation). Version 1.2.0, released regularly. Key differentiators: built-in high-performance memory (4096D) with pgvector support for SOTA embeddings, segregated agent memory per user, autonomous navigation allowing natural language queries without SQL. Provides both a CLI MCP server for tools like table browsing, query execution, and schema extraction, and a TypeScript library for programmatic embedding and hybrid search. Requires Node.js >=20 <25 and a PostgreSQL instance with pgvector extension. Competes with other PostgreSQL MCP servers but focuses on agent-oriented memory and semantic capabilities.

Common errors

error Error: Cannot find module 'overmind-postgres-mcp/services/embeddings' ↓

cause Typo in import path or wrong installation path.

fix

Install locally: npm install overmind-postgres-mcp, then use correct import path.

error Error: The module 'overmind-postgres-mcp' does not provide a default export. ↓

cause Trying to import default export when package has none.

fix

Use named exports from subpaths, e.g., import { embedText } from 'overmind-postgres-mcp/services/embeddings'.

error TypeError: Cannot read properties of undefined (reading 'query') ↓

cause POSTGRES_URL not set or incorrect.

fix

Set POSTGRES_URL in .env or environment variables.

error Error: connect ECONNREFUSED ::1:5432 ↓

cause PostgreSQL not running or not accessible.

fix

Start PostgreSQL service and verify connection string.

Warnings

breaking Requires Node.js version >=20 and <25. Older versions will not work. ↓

fix Upgrade Node.js to v20 or v21/v22 (but not v25). Use nvm or similar.

deprecated The 'embedText' function uses an embedding model that may change without notice. For production, pin the model version. ↓

fix Check documentation for available model options and pass explicit model parameter.

gotcha .env file must contain OPEN_ROUTER_API_KEY; the package will fail silently if missing. ↓

fix Ensure OPEN_ROUTER_API_KEY is set in environment or .env file.

gotcha The PostgreSQL database must have the pgvector extension installed for embeddings to work. ↓

fix Run 'CREATE EXTENSION IF NOT EXISTS vector;' on your PostgreSQL instance.

breaking Global installation (npm install -g) may conflict with other MCP servers if not scoped correctly. ↓

fix Use npx to avoid global conflicts, or install locally.

Install

npm install overmind-postgres-mcp

yarn add overmind-postgres-mcp

pnpm add overmind-postgres-mcp

Imports

embedText

wrong

import { embedText } from 'overmind-postgres-mcp'

correct

import { embedText } from 'overmind-postgres-mcp/services/embeddings'

This is a service export, not a main package export. Must use deep import path.

IntelligentSearchService

wrong

const { IntelligentSearchService } = require('overmind-postgres-mcp/services/search')

correct

import { IntelligentSearchService } from 'overmind-postgres-mcp/services/search'

TypeScript library requires ESM; CommonJS require is not supported.

Default export (none)
wrong
```
import server from 'overmind-postgres-mcp'
```
correct
```
import { something } from 'overmind-postgres-mcp'
```
Package does not have a default export; only named exports from subpaths.

Quickstart

Shows two ways: CLI MCP server setup via .mcp.json and .env, and programmatic embedding usage.

// 1. Set environment variables
const POSTGRES_URL = process.env.POSTGRES_URL ?? 'postgresql://user:pass@localhost:5432/mydb';
const OPEN_ROUTER_API_KEY = process.env.OPEN_ROUTER_API_KEY ?? 'sk-or-v1-...';

// 2. Run the MCP server via CLI
// npx -y overmind-postgres-mcp

// 3. Or programmatically use embeddings
import { embedText } from 'overmind-postgres-mcp/services/embeddings';

async function main() {
  const { embedding, model } = await embedText('Your text here');
  console.log('Embedding vector:', embedding.slice(0, 5), '...');
  console.log('Model used:', model);
}
main().catch(console.error);