PostgreSQL MCP Server v1.2.0 Release Notes

Release Date: December 2025
Docker Image: writenotenow/postgres-mcp-enhanced:v1.2.0
PyPI Package: postgres-mcp-enhanced v1.2.0

🎉 What's New in v1.2.0

This is a feature release introducing intelligent tool filtering to optimize the PostgreSQL MCP Server for any client. Version 1.2.0 solves client tool limits, reduces token consumption, and improves performance while maintaining 100% backward compatibility.

🎛️ Major Feature: Tool Filtering

NEW: POSTGRES_MCP_TOOL_FILTER Environment Variable

Control which tools are exposed to your MCP client with a simple, flexible filtering system:

# Windsurf (100-tool limit) - reduces to ~35 tools
POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-stats,-text"

# No pgvector/PostGIS extensions - reduces to 48 tools
POSTGRES_MCP_TOOL_FILTER="-vector,-geo"

# Core database only - reduces to 9 tools
POSTGRES_MCP_TOOL_FILTER="-json,-text,-stats,-performance,-vector,-geo,-backup,-monitoring"

Why Tool Filtering Matters

✅ Client Compatibility

Stay under Windsurf's 100-tool hard limit
Avoid Cursor's performance warnings at ~80 tools
Improve stability for all MCP clients

✅ Token Savings (24-86% reduction)

44% savings: ~5,600 tokens with -vector,-geo,-stats,-text
24% savings: ~3,000 tokens with -vector,-geo
86% savings: ~10,800 tokens with core-only configuration

✅ Cost Reduction

Save $1.68-$3.24 per conversation (GPT-4 pricing)
Save $900-$3,240 per 1,000 conversations
Reduce token overhead without losing functionality

✅ Performance Benefits

Faster tool discovery by AI
Better tool selection with reduced noise
Lower API latency with smaller payloads
More context space for actual data

✅ Smart Filtering

Remove tools requiring missing PostgreSQL extensions
Disable execute_sql for read-only environments
Customize tool sets by use case (dev, prod, CI/CD, analytics)

🎯 Key Features

Flexible Filter Syntax

Syntax	Description	Example
`-group`	Disable all tools in a group	`-vector` disables 8 vector tools
`-tool`	Disable a specific tool	`-execute_sql` disables only execute_sql
`+tool`	Re-enable a tool after group disable	`+list_schemas` re-enables list_schemas

Rules process left-to-right - order matters for fine-grained control!

9 Tool Groups

Group	Tool Count	Description
`core`	9	Schema management, SQL execution, health monitoring
`json`	11	JSONB operations, validation, security scanning
`text`	5	Similarity search, full-text search, fuzzy matching
`stats`	8	Descriptive stats, correlation, regression, time series
`performance`	6	Query optimization, index tuning, workload analysis
`vector`	8	Embeddings, similarity search, clustering (requires pgvector)
`geo`	7	Distance calculation, spatial queries (requires PostGIS)
`backup`	4	Backup planning, restore validation, scheduling
`monitoring`	5	Real-time monitoring, capacity planning, alerting

Total: 63 tools across 9 groups

Token Savings Calculator

Configuration	Tools	Tokens Saved	Savings %	Cost Saved/Conversation*
No filtering	63	0	0%	$0
`-vector,-geo,-stats,-text`	35	~5,600	44%	$1.68
`-vector,-geo`	48	~3,000	24%	$0.90
Core + JSON only	20	~8,600	68%	$2.58
Core only	9	~10,800	86%	$3.24

*Based on GPT-4 pricing (~$0.03/1K tokens) for 10-exchange conversation

🚀 Quick Start

Docker with Tool Filtering

# Pull the latest image
docker pull writenotenow/postgres-mcp-enhanced:v1.2.0

# Run with Windsurf-optimized filtering
docker run -i --rm \
  -e DATABASE_URI="postgresql://user:pass@localhost:5432/db" \
  -e POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-stats,-text" \
  writenotenow/postgres-mcp-enhanced:v1.2.0 \
  --access-mode=restricted

Python Installation

# Install from PyPI
pip install postgres-mcp-enhanced==1.2.0

# Set filter in your environment
export POSTGRES_MCP_TOOL_FILTER="-vector,-geo"
postgres-mcp --access-mode=restricted

One-Click Cursor Installation

🔧 Configuration Examples

Windsurf (100-Tool Limit)

Add to MCP settings:

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-e", "DATABASE_URI", "-e", "POSTGRES_MCP_TOOL_FILTER",
        "writenotenow/postgres-mcp-enhanced:v1.2.0",
        "--access-mode=restricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://user:pass@localhost:5432/db",
        "POSTGRES_MCP_TOOL_FILTER": "-vector,-geo,-stats,-text"
      }
    }
  }
}

Result: 35 tools exposed, well under 100-tool limit, 44% token savings

Cursor IDE (Optimal Performance)

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "postgres-mcp",
      "args": ["--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "postgresql://user:pass@localhost:5432/db",
        "POSTGRES_MCP_TOOL_FILTER": "-vector,-geo"
      }
    }
  }
}

Result: 48 tools, avoids ~80 tool warning, 24% token savings

Claude Desktop (No Extensions)

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-e", "DATABASE_URI", "-e", "POSTGRES_MCP_TOOL_FILTER",
        "writenotenow/postgres-mcp-enhanced:v1.2.0",
        "--access-mode=restricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://user:pass@localhost:5432/db",
        "POSTGRES_MCP_TOOL_FILTER": "-vector,-geo"
      }
    }
  }
}

Result: Removes 15 tools requiring pgvector/PostGIS, prevents errors

Common Use Cases

# Development - all tools except missing extensions
POSTGRES_MCP_TOOL_FILTER="-vector,-geo"

# Analytics focus - keep stats/performance
POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-backup"

# Read-only production
POSTGRES_MCP_TOOL_FILTER="-execute_sql"

# CI/CD pipelines - core operations only
POSTGRES_MCP_TOOL_FILTER="-backup,-monitoring"

# Cost-conscious - minimal footprint
POSTGRES_MCP_TOOL_FILTER="-json,-text,-stats,-performance,-vector,-geo,-backup,-monitoring"

📦 Complete Feature Set

63 MCP Tools Across 9 Categories

All tools remain available with backward compatibility. Use filtering to customize your experience.

Category	Tools	Description
Core Database	9	Schema management, SQL execution, health monitoring
JSON Operations	11	JSONB operations, validation, security scanning
Text Processing	5	Similarity search, full-text search, fuzzy matching
Statistical Analysis	8	Descriptive stats, correlation, regression, time series
Performance Intelligence	6	Query optimization, index tuning, workload analysis
Vector/Semantic Search	8	Embeddings, similarity search, clustering
Geospatial	7	Distance calculation, spatial queries, GIS operations
Backup & Recovery	4	Backup planning, restore validation, scheduling
Monitoring & Alerting	5	Real-time monitoring, capacity planning, alerting

10 MCP Resources - Database Meta-Awareness

Real-time database context that AI can access automatically:

database://schema - Complete database structure
database://capabilities - Server features and extensions
database://performance - Query performance metrics
database://health - Database health status
database://extensions - Extension inventory
database://indexes - Index usage statistics
database://connections - Connection pool status
database://replication - Replication lag and status
database://vacuum - Vacuum and wraparound status
database://locks - Lock contention information
database://statistics - Statistics quality

10 MCP Prompts - Guided Workflows

Step-by-step workflows for complex operations:

optimize_query - Query optimization workflow
index_tuning - Index analysis and recommendations
database_health_check - Comprehensive health assessment
setup_pgvector - pgvector installation and setup
json_operations - JSONB best practices
performance_baseline - Baseline establishment
backup_strategy - Backup planning and design
setup_postgis - PostGIS installation and usage
explain_analyze_workflow - Deep plan analysis
extension_setup - Extension installation guide

🛡️ Security & Quality

✅ Zero Known Vulnerabilities - Comprehensive security audit passed
✅ Pyright Strict Mode - 100% type-safe codebase (2,000+ issues resolved)
✅ SQL Injection Prevention - All queries use parameter binding
✅ 20+ Security Tests - All attack vectors covered
✅ CodeQL Scanning - Continuous security monitoring
✅ Dual Security Modes - Restricted (production) and unrestricted (development)
✅ Tool Filtering Security - Filter validation at server startup

📚 Documentation

New in v1.2.0

Tool Filtering Guide - Complete filtering documentation with best practices

Core Documentation

Complete Wiki - Full documentation with examples
Quick Start Guide - Get running in 30 seconds
Installation Guide - Detailed setup instructions
Security Best Practices - Production security
Troubleshooting - Common issues and solutions

Tools & Search

🔍 AI-Powered Documentation Search - Natural language search across all tools
📝 GitHub Gists - 7 practical examples and use cases
📰 Release Article - Deep dive into enterprise features

Distribution

🐳 Docker Hub - Container images
📦 PyPI Package - Python distribution
🌐 MCP Registry - Official MCP listing

🔄 Upgrade Guide

From v1.1.x to v1.2.0

This is a drop-in replacement with no breaking changes. Tool filtering is completely optional.

Docker:

docker pull writenotenow/postgres-mcp-enhanced:v1.2.0
# Update your config to use v1.2.0 tag
# Optionally add POSTGRES_MCP_TOOL_FILTER to env section

Python:

pip install --upgrade postgres-mcp-enhanced
# Optionally set POSTGRES_MCP_TOOL_FILTER environment variable

Behavior:

Without filter: All 63 tools exposed (same as v1.1.x)
With filter: Tools filtered according to your configuration
All existing configurations work unchanged

Recommended Upgrade Steps

Pull v1.2.0 - Get the latest version
Test without filtering - Verify everything works as before
Add filtering - If needed, configure POSTGRES_MCP_TOOL_FILTER
Verify tool count - Check database://capabilities resource
Enjoy savings - Benefit from reduced token consumption!

✨ What's Changed

New Features

✅ Tool filtering system with 9 groups
✅ POSTGRES_MCP_TOOL_FILTER environment variable
✅ Flexible filter syntax: -group, -tool, +tool
✅ Server-side filtering for maximum compatibility
✅ Filter validation and logging at startup

Improvements

✅ Enhanced documentation with filtering examples
✅ Updated all configuration examples
✅ Improved error messages for disabled tools
✅ Better logging for filter rule processing

Documentation

✅ New Tool Filtering wiki page
✅ Updated README with filtering section
✅ Updated Docker README with filtering
✅ Comprehensive CHANGELOG entry
✅ Token savings calculator

Testing

✅ Comprehensive system testing of all 63 tools
✅ Filter validation tests
✅ Backward compatibility verification
✅ Multi-client compatibility testing

📊 Technical Specifications

PostgreSQL Compatibility: 13, 14, 15, 16, 17, 18
Python Version: 3.12, 3.13, 3.14
Platform Support: Windows, Linux, macOS (amd64, arm64)
Container Size: ~240MB uncompressed
Dependencies: Fully pinned and audited
Code Quality: Pyright strict mode, zero linter errors
Test Coverage: 90%+ with comprehensive integration tests
Tool Filtering: Server-side, zero-configuration default

💡 Real-World Examples

Example 1: Windsurf User

Problem: 100-tool limit exceeded with 63 PostgreSQL tools
Solution: POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-stats,-text"
Result: 35 tools, 44% token savings, stable operation

Example 2: Cost-Conscious Startup

Problem: High API costs with frequent database queries
Solution: POSTGRES_MCP_TOOL_FILTER="-json,-text,-stats,-performance,-vector,-geo,-backup,-monitoring"
Result: 9 core tools, 86% token savings, $3.24 saved per conversation

Example 3: Production Environment

Problem: Don't have pgvector/PostGIS installed, getting errors
Solution: POSTGRES_MCP_TOOL_FILTER="-vector,-geo"
Result: 48 tools, no extension errors, 24% token savings

Example 4: CI/CD Pipeline

Problem: Don't need backup/monitoring tools in automated tests
Solution: POSTGRES_MCP_TOOL_FILTER="-backup,-monitoring"
Result: 54 tools focused on core operations, faster execution

Example 5: Analytics Team

Problem: Need stats but not spatial operations
Solution: POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-backup"
Result: 52 tools optimized for data analysis

🏆 Why Choose This Server?

✅ Most Comprehensive - 63 tools + 10 resources + 10 prompts
✅ Most Flexible - NEW: Tool filtering for any use case
✅ Production Ready - Zero known vulnerabilities, enterprise-grade
✅ Cost Efficient - NEW: Save up to 86% on token overhead
✅ AI-Native - Vector search, semantic operations, ML-ready
✅ Intelligent - Meta-awareness and guided workflows
✅ Client Compatible - NEW: Works with Windsurf, Cursor, Claude Desktop
✅ Active Maintenance - Regular updates and security patches
✅ Well Documented - 16-page wiki + AI-powered search
✅ Type Safe - 100% Pyright strict mode compliance
✅ Multi-Platform - Docker + Python + pip installation options

📝 Changelog Summary

v1.2.0 (December 2025) - Tool Filtering

NEW: Tool filtering with POSTGRES_MCP_TOOL_FILTER environment variable
NEW: 9 tool groups for flexible configuration
NEW: Token savings of 24-86% based on configuration
NEW: Comprehensive Tool Filtering documentation
IMPROVED: Client compatibility (Windsurf, Cursor)
IMPROVED: Cost efficiency with reduced token overhead
ZERO BREAKING CHANGES: All tools enabled by default

v1.1.1 (December 6, 2025)

Enhanced stability and error handling
Performance optimizations for large databases
Documentation improvements
Security dependency updates

v1.1.0 (October 4, 2025)

Added 10 MCP Resources for database meta-awareness
Added 10 MCP Prompts for guided workflows
Transformed into intelligent database assistant
Pyright strict mode compliance

v1.0.0 (October 3, 2025)

Production release with 63 specialized tools
Enterprise-grade security and testing
Multi-platform Docker support

🎓 Best Practices

When to Use Tool Filtering

✅ Use filtering when:

Your MCP client has tool limits (Windsurf: 100, Cursor: ~80)
You want to reduce token consumption and API costs
You don't have pgvector or PostGIS installed
You need read-only operations (disable execute_sql)
You're running in CI/CD (core operations only)
You want faster AI tool discovery

✅ Keep all tools when:

You have no client limits
Token costs are not a concern
You have all extensions installed
You need maximum flexibility
You're exploring the full feature set

Recommended Configurations by Environment

Development:

POSTGRES_MCP_TOOL_FILTER="-vector,-geo"  # If extensions not installed

Production (Windsurf):

POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-stats,-text"

Production (Cursor):

POSTGRES_MCP_TOOL_FILTER="-vector,-geo"

CI/CD:

POSTGRES_MCP_TOOL_FILTER="-backup,-monitoring"

Analytics:

POSTGRES_MCP_TOOL_FILTER="-vector,-geo,-backup"

Cost-Conscious:

POSTGRES_MCP_TOOL_FILTER="-json,-text,-stats,-performance,-vector,-geo,-backup,-monitoring"

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Report Issues: GitHub Issues
Security: Report vulnerabilities to [email protected]
Discussions: GitHub Discussions

📄 License

MIT License - See LICENSE file for details.

🙏 Acknowledgments

Thank you to the PostgreSQL community, MCP developers, Windsurf and Cursor teams for feedback on tool limits, and all contributors who made this release possible!

Special thanks to the community for requesting and providing feedback on tool filtering capabilities.

⭐ If you find this project useful, please star it on GitHub!

📥 Download:

Docker: docker pull writenotenow/postgres-mcp-enhanced:v1.2.0
PyPI: pip install postgres-mcp-enhanced==1.2.0
Source: GitHub Release

🔗 Quick Links:

Built by developers, for developers. 🚀

PostgreSQL MCP v1.2.0 - Tool Filtering & Token Efficiency Latest