PostgreSQL Retail
A Model Context Protocol (MCP) server that provides comprehensive customer sales database access for Zava Retail DIY Business. This server enables AI assistants to query and analyze retail sales data through a secure, schema-aware interface.
What is PostgreSQL Retail?
PostgreSQL Retail is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to model context protocol (mcp) server that provides comprehensive customer sales database access for zava retail diy business. this server enables ai assistants to query and analyze retail sales data th...
A Model Context Protocol (MCP) server that provides comprehensive customer sales database access for Zava Retail DIY Business. This server enables AI assistants to query and analyze retail sales data through a secure, schema-aware interface.
This server falls under the Databases category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A Model Context Protocol (MCP) server that provides comprehe
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx mcp-server-and-postgresql-sample-retailConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use PostgreSQL Retail
This MCP server is a reference implementation from Microsoft that connects AI assistants to a PostgreSQL retail sales database for the fictional Zava Retail DIY Business. It exposes schema-aware query tools with Row Level Security so different store users only see their own data. Developers can use it as a working pattern for building secure, multi-tenant MCP database integrations with PostgreSQL and Azure AI embeddings.
Prerequisites
- Docker and Docker Compose installed (used to run PostgreSQL and the MCP server)
- Azure CLI installed and authenticated via 'az login' (needed for embedding model access)
- Git to clone the repository
- An MCP-compatible client such as Claude Desktop or VS Code with the MCP extension
- Node.js is not required — the server runs entirely in Docker
Clone the repository
Clone the Microsoft sample repository which contains the Docker Compose configuration, database seed scripts, and MCP server code.
git clone https://github.com/microsoft/MCP-Server-and-PostgreSQL-Sample-Retail.git
cd MCP-Server-and-PostgreSQL-Sample-RetailAuthenticate with Azure
Log in with the Azure CLI so the server can access the Azure OpenAI embedding model used by the semantic_search_products tool.
az loginCopy and configure environment variables
Copy the provided template to .env and fill in your Azure OpenAI endpoint and deployment details. The file controls the embedding model connection.
cp .env.template .env
# Edit .env with your Azure OpenAI endpoint and deployment nameStart the stack with Docker Compose
This brings up PostgreSQL (with the retail schema pre-seeded) and the MCP HTTP server on port 8000.
docker compose up -dConfigure your MCP client
Connect your MCP client to the running server using HTTP transport. Different x-rls-user-id header values correspond to different store employees, enforcing Row Level Security. The head-office UUID shown below grants access to all stores.
{
"servers": {
"zava-sales-analysis-headoffice": {
"url": "http://127.0.0.1:8000/mcp",
"type": "http",
"headers": {
"x-rls-user-id": "00000000-0000-0000-0000-000000000000"
}
}
}
}Verify the server is responding
Check that all containers are running and the MCP endpoint is reachable before connecting your AI client.
docker compose ps
curl http://127.0.0.1:8000/mcpPostgreSQL Retail Examples
Client configuration
VS Code MCP client config connecting to the local HTTP server with head-office Row Level Security access.
{
"servers": {
"zava-sales-analysis-headoffice": {
"url": "http://127.0.0.1:8000/mcp",
"type": "http",
"headers": {
"x-rls-user-id": "00000000-0000-0000-0000-000000000000"
}
}
}
}Prompts to try
Natural language queries that map to the four exposed MCP tools.
- "Show top 20 products by sales revenue this year"
- "What were last quarter's sales broken down by category?"
- "Show me sales performance by store location"
- "Find products similar to 'containers for paint' using semantic search"
- "What is today's UTC date?"Troubleshooting PostgreSQL Retail
Docker Compose fails to start with a database connection error
Wait 10-15 seconds after 'docker compose up -d' for PostgreSQL to finish initializing, then check logs with 'docker compose logs db'. If the schema is missing, run 'docker compose down -v && docker compose up -d' to reset the volumes.
The semantic_search_products tool returns an authentication error
Re-run 'az login' to refresh your Azure credentials. Ensure your .env file contains the correct AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT_NAME values and that your Azure account has access to the specified embedding deployment.
Queries return no data or only a subset of records
This is likely the Row Level Security working correctly. The x-rls-user-id header in your config restricts data to a specific store. Use the head-office UUID (all zeros) to access data across all stores.
Frequently Asked Questions about PostgreSQL Retail
What is PostgreSQL Retail?
PostgreSQL Retail is a Model Context Protocol (MCP) server that model context protocol (mcp) server that provides comprehensive customer sales database access for zava retail diy business. this server enables ai assistants to query and analyze retail sales data through a secure, schema-aware interface. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install PostgreSQL Retail?
Follow the installation instructions on the PostgreSQL Retail GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with PostgreSQL Retail?
PostgreSQL Retail works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is PostgreSQL Retail free to use?
Yes, PostgreSQL Retail is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
PostgreSQL Retail Alternatives — Similar Databases Servers
Looking for alternatives to PostgreSQL Retail? Here are other popular databases servers you can use with Claude, Cursor, and VS Code.
Excelize
★ 20.6kGo language library for reading and writing Microsoft Excel™ (XLAM / XLSM / XLSX / XLTM / XLTX) spreadsheets
MCP Toolbox for Databases
★ 15.3kOpen source MCP server specializing in easy, fast, and secure tools for Databases.
DBHub
★ 2.8kA universal database gateway MCP server that enables AI assistants to connect to and query multiple databases (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite) with support for schema exploration, SQL execution, and secure connections via SSH tunnels.
Tabularis
★ 2.1kA lightweight, cross-platform database client for developers. Supports MySQL, PostgreSQL and SQLite. Hackable with plugins. Built for speed, security, and aesthetics.
Postgres AI Guide
★ 1.7kMCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code.
Anyquery
★ 1.7k🏎️ 🏠 ☁️ - Query more than 40 apps with one binary using SQL. It can also connect to your PostgreSQL, MySQL, or SQLite compatible database. Local-first and private by design.
Browse More Databases MCP Servers
Explore all databases servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up PostgreSQL Retail in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use PostgreSQL Retail?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.