PHPackages                             momodemo333/php-mcp-postgresql - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. momodemo333/php-mcp-postgresql

ActiveLibrary[Database & ORM](/categories/database)

momodemo333/php-mcp-postgresql
==============================

PostgreSQL MCP Server for Claude Code - Secure and configurable PostgreSQL integration via Model Context Protocol

v1.0.2(8mo ago)20MITPHPPHP >=8.1CI passing

Since Aug 12Pushed 8mo agoCompare

[ Source](https://github.com/momodemo333/php-mcp-postgresql)[ Packagist](https://packagist.org/packages/momodemo333/php-mcp-postgresql)[ Docs](https://github.com/momodemo333/php-mcp-postgresql)[ RSS](/packages/momodemo333-php-mcp-postgresql/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (1)Versions (4)Used By (0)

🐘 PHP MCP PostgreSQL Server
===========================

[](#-php-mcp-postgresql-server)

[![PHP](https://camo.githubusercontent.com/964517d2570399dcc692858a365295a6d0065689a0647b7074fb3c7ff25ffee2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d2533453d382e312d626c75652e737667)](https://php.net)[![License](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)[![MCP](https://camo.githubusercontent.com/73a628e0630600a792875ec4638d167ba9e0338dd609f75814a1bd5ef0f9eb79/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d43502d332e332d707572706c652e737667)](https://github.com/php-mcp/server)[![Status](https://camo.githubusercontent.com/1dd6b43e3209b2a4cab83ab02f0ddc50d7f5815b48208f669bb9cb9a8796a796/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5374617475732d5749502d6f72616e67652e737667)](IMPLEMENTATION_STATUS.md)

PostgreSQL MCP Server for Claude Code - Secure and configurable PostgreSQL integration via Model Context Protocol.

> 🎉 **Version 1.0.0-beta**: Core functionality complete! Production testing in progress.

🚀 Features
----------

[](#-features)

- 🔒 **Secure by Default** - Read-only operations by default, write operations require explicit permission
- 🎯 **PostgreSQL Native** - Full support for JSONB, arrays, CTEs, window functions, and more
- ⚡ **High Performance** - Connection pooling, prepared statements, query timeouts
- 📊 **Schema Introspection** - Explore databases, tables, columns, indexes
- 🔧 **Flexible Configuration** - Environment variables, .env files, multi-database support
- 🛡️ **Built-in Protection** - SQL injection prevention, dangerous keyword blocking, result limits

📦 Requirements
--------------

[](#-requirements)

- PHP 8.1 or higher
- PostgreSQL 12 or higher
- Composer
- PHP extensions: `ext-pdo`, `ext-pdo_pgsql`

🔧 Installation
--------------

[](#-installation)

### 1. Clone the Repository

[](#1-clone-the-repository)

```
git clone https://github.com/momodemo333/php-mcp-postgresql.git
cd php-mcp-postgresql
```

### 2. Install Dependencies

[](#2-install-dependencies)

```
composer install
```

### 3. Configure Environment

[](#3-configure-environment)

```
cp .env.example .env
# Edit .env with your PostgreSQL credentials
```

⚙️ Configuration
----------------

[](#️-configuration)

### Environment Variables

[](#environment-variables)

VariableDescriptionDefault`PGSQL_HOST`PostgreSQL server hostlocalhost`PGSQL_PORT`PostgreSQL server port5432`PGSQL_USER`Database usernamepostgres`PGSQL_PASS`Database password(empty)`PGSQL_DB`Database name (optional for multi-db)(empty)`ALLOW_INSERT_OPERATION`Enable INSERT queriesfalse`ALLOW_UPDATE_OPERATION`Enable UPDATE queriesfalse`ALLOW_DELETE_OPERATION`Enable DELETE queriesfalse`QUERY_TIMEOUT`Query timeout in seconds30`MAX_RESULTS`Maximum rows returned1000`CONNECTION_POOL_SIZE`Max concurrent connections5`LOG_LEVEL`Logging level (DEBUG/INFO/WARN/ERROR)INFO### Claude Code Configuration

[](#claude-code-configuration)

Add to your Claude Code settings (`claude-code-settings.json`):

```
{
  "mcpServers": {
    "postgresql": {
      "command": "php",
      "args": ["/absolute/path/to/php-mcp-postgresql/bin/server.php"],
      "type": "stdio",
      "env": {
        "PGSQL_HOST": "localhost",
        "PGSQL_PORT": "5432",
        "PGSQL_USER": "your_user",
        "PGSQL_PASS": "your_password",
        "PGSQL_DB": "your_database"
      }
    }
  }
}
```

See [examples/](examples/) for more configuration examples.

🛠️ Available Tools
------------------

[](#️-available-tools)

### Database Management

[](#database-management)

- **`pgsql_list_databases`** - List all available databases
- **`pgsql_list_tables`** - List tables in a database
- **`pgsql_describe_table`** - Get detailed table structure
- **`pgsql_server_status`** - Get server status and statistics

### Query Execution

[](#query-execution)

- **`pgsql_select`** - Execute SELECT queries safely
- **`pgsql_insert`** - Insert data (requires permission)
- **`pgsql_update`** - Update data (requires permission)
- **`pgsql_delete`** - Delete data (requires permission)
- **`pgsql_execute_query`** - Execute custom queries (with validation)

🧪 Testing
---------

[](#-testing)

### Quick Test

[](#quick-test)

```
# Start test PostgreSQL database
./tests/start-test-db.sh

# Run all tests
./tests/run-tests.sh

# Stop test database
./tests/stop-test-db.sh
```

### Docker Test Environment

[](#docker-test-environment)

The project includes a complete Docker test environment:

```
# Start PostgreSQL container with test data
docker-compose -f docker-compose.test.yml up -d

# Run tests
php tests/test_connection.php
php tests/test_mcp_server.php

# Stop containers
docker-compose -f docker-compose.test.yml down
```

🔒 Security
----------

[](#-security)

### Default Security Features

[](#default-security-features)

- **Read-only by default** - All write operations disabled unless explicitly enabled
- **Prepared statements** - Prevents SQL injection attacks
- **Query validation** - Blocks dangerous keywords and operations
- **Result limits** - Prevents memory exhaustion from large result sets
- **Connection timeouts** - Prevents hanging queries
- **Schema restrictions** - Limit access to specific schemas

### Best Practices

[](#best-practices)

1. Never enable write operations in production unless absolutely necessary
2. Use read-only database users when possible
3. Set appropriate `MAX_RESULTS` and `QUERY_TIMEOUT` values
4. Review logs regularly for suspicious activity
5. Keep the server updated with security patches

🎆 PostgreSQL-Specific Features
------------------------------

[](#-postgresql-specific-features)

### JSONB Support

[](#jsonb-support)

```
-- Query JSONB fields
SELECT * FROM users WHERE metadata->>'role' = 'admin';
SELECT * FROM products WHERE specifications @> '{"cpu": "Intel i7"}';
```

### Array Support

[](#array-support)

```
-- Query array fields
SELECT * FROM products WHERE 'electronics' = ANY(tags);
SELECT * FROM products WHERE tags && ARRAY['computers', 'portable'];
```

### Advanced Features

[](#advanced-features)

- Common Table Expressions (CTEs)
- Window functions
- RETURNING clause on INSERT/UPDATE/DELETE
- Materialized views
- Full-text search
- Custom types and domains

📝 Documentation
---------------

[](#-documentation)

- [Installation Guide](docs/installation.md)
- [Configuration Reference](docs/mcp-configuration.md)
- [MCP Tools Documentation](docs/mcp-tools.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Migration Plan](MIGRATION_PLAN.md)
- [Implementation Status](IMPLEMENTATION_STATUS.md)

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

📄 License
---------

[](#-license)

MIT License - see [LICENSE](LICENSE) file for details.

🙏 Acknowledgments
-----------------

[](#-acknowledgments)

- Built with [php-mcp/server](https://github.com/php-mcp/server) framework
- Based on [php-mcp-mysql](https://github.com/momodemo333/php-mcp-mysql) architecture
- Thanks to the MCP community for the protocol specification

💬 Support
---------

[](#-support)

- **Issues**: [GitHub Issues](https://github.com/momodemo333/php-mcp-postgresql/issues)
- **Discussions**: [GitHub Discussions](https://github.com/momodemo333/php-mcp-postgresql/discussions)

---

**Version**: 1.0.0-beta
**Status**: Production Testing
**Last Updated**: January 2025

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance60

Regular maintenance activity

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~10 days

Total

3

Last Release

260d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/feba37b54dd366f8d54716c59d586a4af2408fcf5bd88d034a102149ae361e80?d=identicon)[momodemo333](/maintainers/momodemo333)

---

Top Contributors

[![momodemo333](https://avatars.githubusercontent.com/u/81758876?v=4)](https://github.com/momodemo333 "momodemo333 (47 commits)")

---

Tags

mcpdatabaseaipostgresqlpostgrespgsqlclaude-codeModel Context Protocolphp mcp

### Embed Badge

![Health badge](/badges/momodemo333-php-mcp-postgresql/health.svg)

```
[![Health](https://phpackages.com/badges/momodemo333-php-mcp-postgresql/health.svg)](https://phpackages.com/packages/momodemo333-php-mcp-postgresql)
```

###  Alternatives

[doctrine/dbal

Powerful PHP database abstraction layer (DBAL) with many features for database schema introspection and management.

9.7k578.4M5.6k](/packages/doctrine-dbal)[aura/sqlquery

Object-oriented query builders for MySQL, Postgres, SQLite, and SQLServer; can be used with any database connection library.

4572.9M34](/packages/aura-sqlquery)[atlas/query

Object-oriented query builders and performers for MySQL, Postgres, SQLite, and SQLServer.

41249.0k7](/packages/atlas-query)[aura/sqlschema

Provides facilities to read table names and table columns from a database using PDO.

41234.1k4](/packages/aura-sqlschema)[amphp/postgres

Asynchronous PostgreSQL client for Amp.

110509.8k27](/packages/amphp-postgres)[delight-im/db

Safe and convenient SQL database access in a driver-agnostic way

49156.8k7](/packages/delight-im-db)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)