You can run a self-contained MCP-powered data analysis dashboard that lets you ask questions in natural language, generate SQL via an LLM, query PostgreSQL, visualize results, and export data. This server setup focuses on exposing structured SQL-related capabilities to a local or remote MCP client, giving you control, transparency, and local execution.

How to use

You interact with the system through an MCP client that communicates with the MCP API. You ask a data question in natural language, and the client sends it to Ollama for translation into SQL. The resulting SQL is sent to the MCP server, which executes it against PostgreSQL and returns results. You can view charts, obtain statistics, and export data as CSV. The workflow emphasizes interpretability, flexibility, and full local control.

How to install

# Prerequisites
# - Docker and Docker Compose
# - Git

# 1) Clone the project repository
git clone <this-repo>
cd postgres-mcp-server

# 2) Build and start the services
docker-compose up --build

Access the user interface at:

• UI: http://localhost:8501
• MCP API: http://localhost:3333/mcp

Optional: verify environment variables (defined in the runtime environment)

MCP_API_URL should point to the MCP API endpoint for your setup

OLLAMA_URL should point to the Ollama generation API

## Configuration and usage notes

The system uses two key environment variables to wire components:
- MCP\_API\_URL=http://mcp-server:3333/mcp
- OLLAMA\_URL=http://ollama:11434/api/generate
These enable the MCP client to reach the MCP server and the Ollama LLM interface for translating natural language prompts into SQL.

If you run the services locally with Docker Compose, keep the default localhost endpoints or adjust them to match your network setup. The MCP API endpoint is the primary entry point for the MCP client to discover available tools and perform SQL-related operations.

## Examples and tips

Prompt example: “List departments with average salary > 50000” translates to a SQL statement like:
```SELECT department, AVG(salary) FROM employees GROUP BY department HAVING AVG(salary) > 50000;```
This shows how natural language queries map to actionable SQL that the MCP server executes against PostgreSQL.

Tip: Expose structured tools to LLMs for better interpretability and control. MCP lets you provide explicit endpoints for SQL execution and table listing, helping you manage what capabilities the LLMs can invoke and how results are surfaced.

## Troubleshooting

If the MCP UI cannot reach the MCP API, verify that http://localhost:3333/mcp is reachable from your network. Check Docker Compose status, and ensure the MCP server container is starting correctly. Also confirm that Ollama is accessible at the configured OLLAMA\_URL and that PostgreSQL is running and reachable by the MCP service.

## Available tools

### execute\_sql

Executes SQL queries on the PostgreSQL database and returns results to the MCP client.

### list\_tables

Lists available tables in the PostgreSQL database so the client can present schema information to users.