{"id":31287601,"url":"https://github.com/sgaunet/postgresql-mcp","last_synced_at":"2025-09-24T11:04:30.344Z","repository":{"id":315805722,"uuid":"1060736136","full_name":"sgaunet/postgresql-mcp","owner":"sgaunet","description":"A Model Context Protocol (MCP) server that provides secure PostgreSQL database integration tools for Claude Code. Features read-only query execution, schema exploration, and performance analysis.","archived":false,"fork":false,"pushed_at":"2025-09-20T21:14:30.000Z","size":63,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T21:30:22.653Z","etag":null,"topics":["ai-tools","claude-code","database","database-tools","golang","mcp","mcp-server","postgresql","read-only","sql"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sgaunet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["sgaunet"]}},"created_at":"2025-09-20T13:43:23.000Z","updated_at":"2025-09-20T21:20:39.000Z","dependencies_parsed_at":"2025-09-20T21:30:34.949Z","dependency_job_id":"2ace7e70-5d65-4dba-a146-0478d2e8d19b","html_url":"https://github.com/sgaunet/postgresql-mcp","commit_stats":null,"previous_names":["sgaunet/postgresql-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/sgaunet/postgresql-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgaunet%2Fpostgresql-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgaunet%2Fpostgresql-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgaunet%2Fpostgresql-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgaunet%2Fpostgresql-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sgaunet","download_url":"https://codeload.github.com/sgaunet/postgresql-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgaunet%2Fpostgresql-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276737524,"owners_count":25695700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-24T02:00:09.776Z","response_time":97,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","claude-code","database","database-tools","golang","mcp","mcp-server","postgresql","read-only","sql"],"created_at":"2025-09-24T11:01:55.853Z","updated_at":"2025-09-24T11:04:30.338Z","avatar_url":"https://github.com/sgaunet.png","language":"Go","funding_links":["https://github.com/sponsors/sgaunet"],"categories":[],"sub_categories":[],"readme":"# PostgreSQL MCP Server\n\n[![GitHub release](https://img.shields.io/github/release/sgaunet/postgresql-mcp.svg)](https://github.com/sgaunet/postgresql-mcp/releases/latest)\n[![Go Report Card](https://goreportcard.com/badge/github.com/sgaunet/postgresql-mcp)](https://goreportcard.com/report/github.com/sgaunet/postgresql-mcp)\n![GitHub Downloads](https://img.shields.io/github/downloads/sgaunet/postgresql-mcp/total)\n![Coverage](https://raw.githubusercontent.com/wiki/sgaunet/postgresql-mcp/coverage-badge.svg)\n[![coverage](https://github.com/sgaunet/postgresql-mcp/actions/workflows/coverage.yml/badge.svg)](https://github.com/sgaunet/postgresql-mcp/actions/workflows/coverage.yml)\n[![Snapshot Build](https://github.com/sgaunet/postgresql-mcp/actions/workflows/snapshot.yml/badge.svg)](https://github.com/sgaunet/postgresql-mcp/actions/workflows/snapshot.yml)\n[![Release Build](https://github.com/sgaunet/postgresql-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/sgaunet/postgresql-mcp/actions/workflows/release.yml)\n[![License](https://img.shields.io/github/license/sgaunet/postgresql-mcp.svg)](LICENSE)\n\nA Model Context Protocol (MCP) server that provides PostgreSQL integration tools for Claude Code.\n\n## Features\n\n- **List Databases**: List all databases on the PostgreSQL server\n- **List Schemas**: List all schemas in the current database\n- **List Tables**: List tables in a specific schema with optional metadata (size, row count)\n- **Describe Table**: Get detailed table structure (columns, types, constraints, defaults)\n- **Execute Query**: Execute read-only SQL queries (SELECT and WITH statements only)\n- **List Indexes**: List indexes for a specific table with usage statistics\n- **Explain Query**: Get execution plans for SQL queries to analyze performance\n- **Get Table Stats**: Get detailed statistics for tables (row count, size, etc.)\n- Security-first design with read-only operations by default\n- Compatible with Claude Code's MCP architecture\n\n## Prerequisites\n\n- Go 1.25 or later\n- Docker (required for running integration tests)\n- Access to PostgreSQL databases\n\n## Installation\n\n### Option 1: Install with Homebrew (Recommended for macOS/Linux)\n\n```bash\n# Add the tap and install\nbrew tap sgaunet/homebrew-tools\nbrew install sgaunet/tools/postgresql-mcp\n```\n\n### Option 2: Download from GitHub Releases\n\n1. **Download the latest release:**\n\n   Visit the [releases page](https://github.com/sgaunet/postgresql-mcp/releases/latest) and download the appropriate binary for your platform:\n\n   - **macOS**: `postgresql-mcp_VERSION_darwin_amd64` (Intel) or `postgresql-mcp_VERSION_darwin_arm64` (Apple Silicon)\n   - **Linux**: `postgresql-mcp_VERSION_linux_amd64` (x86_64) or `postgresql-mcp_VERSION_linux_arm64` (ARM64)\n   - **Windows**: `postgresql-mcp_VERSION_windows_amd64.exe`\n\n2. **Make it executable (macOS/Linux):**\n   ```bash\n   chmod +x postgresql-mcp_*\n   ```\n\n3. **Move to a location in your PATH:**\n   ```bash\n   # Example for macOS/Linux\n   sudo mv postgresql-mcp_* /usr/local/bin/postgresql-mcp\n   ```\n\n### Option 3: Build from Source\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/sgaunet/postgresql-mcp.git\n   cd postgresql-mcp\n   ```\n\n2. **Build the project:**\n   ```bash\n   task build\n   ```\n\n   Or manually:\n   ```bash\n   go build -o postgresql-mcp\n   ```\n\n3. **Install to your PATH:**\n   ```bash\n   sudo mv postgresql-mcp /usr/local/bin/\n   ```\n\n## Installation for a project\n\nAdd the MCP server in the configuration of the project. At the root of your project, create a file named `.mcap.json' with the following content:\n\n```json\n{\n  \"mcpServers\": {\n    \"postgres\": {\n      \"type\": \"stdio\",\n      \"command\": \"postgresql-mcp\",\n      \"args\": [],\n      \"env\": {\n        \"POSTGRES_URL\": \"postgres://postgres:password@localhost:5432/postgres?sslmode=disable\"\n      }\n    }\n  }\n}\n```\n\nDon't forget to add the .mcp.json file in your .gitignore file if you don't want to commit it. It usually make sense to declare the MCP server for postgresl at the project level, as the database connection is project specific.\n\n## Configuration\n\nThe PostgreSQL MCP server requires database connection information to be provided via environment variables.\n\n### Environment Variables\n\n- `POSTGRES_URL` (required): PostgreSQL connection URL (format: `postgres://user:password@host:port/dbname?sslmode=prefer`)\n- `DATABASE_URL` (alternative): Alternative to `POSTGRES_URL` if `POSTGRES_URL` is not set\n\n**Example:**\n```bash\nexport POSTGRES_URL=\"postgres://user:password@localhost:5432/mydb?sslmode=prefer\"\n# or\nexport DATABASE_URL=\"postgres://user:password@localhost:5432/mydb?sslmode=prefer\"\n```\n\n**Note:** The server will attempt to connect to the database on startup. If the connection fails, it will log a warning and retry when the first tool is requested.\n\n## Available Tools\n\nThe PostgreSQL MCP server provides 8 database tools for interacting with PostgreSQL databases. For detailed information about each tool, including parameters, return values, and examples, see the [Tools Documentation](docs/tools.md).\n\n## Security\n\nThis MCP server is designed with security as a priority:\n\n- **Read-only by default**: Only SELECT and WITH queries are permitted\n- **Parameterized queries**: Protection against SQL injection\n- **Connection validation**: Ensures valid database connections before operations\n- **Error handling**: Comprehensive error handling with detailed logging\n\n## Usage with Claude Code\n\n1. **Configure the MCP server in your Claude Code settings.**\n\n2. **Set up your database connection via environment variables:**\n   ```bash\n   export POSTGRES_URL=\"postgres://user:pass@localhost:5432/mydb\"\n   ```\n\n3. **Use the tools in your conversations:**\n   ```\n   List all tables in the public schema\n   Describe the users table\n   Execute query: SELECT * FROM users LIMIT 10\n   ```\n\n## Documentation\n\n- [Tools Documentation](docs/tools.md) - Detailed reference for all available tools with parameters and examples\n\n## Development\n\n### Building\n```bash\ngo build -o postgresql-mcp\n```\n\n### Testing\n\n#### Unit Tests\n```bash\n# Run unit tests only (no Docker required)\nSKIP_INTEGRATION_TESTS=true go test ./...\n```\n\n#### Integration Tests\n```bash\n# Run all tests including integration tests (requires Docker)\ngo test ./...\n\n# Run only integration tests\ngo test -run \"TestIntegration\" ./...\n```\n\n**Note:** Integration tests use [testcontainers](https://golang.testcontainers.org/) to automatically spin up PostgreSQL instances in Docker containers. This ensures tests are isolated, reproducible, and don't require manual PostgreSQL setup.\n\n### Dependencies\n- [mcp-go](https://github.com/mark3labs/mcp-go) - MCP protocol implementation\n- [lib/pq](https://github.com/lib/pq) - PostgreSQL driver\n- [testcontainers-go](https://github.com/testcontainers/testcontainers-go) - Integration testing with Docker containers\n\n## Troubleshooting\n\n### Connection Issues\n- Verify PostgreSQL is running and accessible\n- Check the `POSTGRES_URL` or `DATABASE_URL` environment variable is correctly set\n- Ensure the connection string format is correct: `postgres://user:password@host:port/dbname?sslmode=prefer`\n- Verify database credentials and permissions\n- Check firewall and network connectivity\n\n### Permission Issues\n- Ensure the database user has appropriate read permissions\n- Verify the user can connect to the specified database\n- Check if the user has access to the schemas and tables you're trying to query\n\n### Query Errors\n- Remember that only SELECT and WITH statements are allowed\n- Ensure proper SQL syntax\n- Check that referenced tables and columns exist\n- Verify you have read permissions on the objects being queried\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request\n\n## License\n\nThis project is licensed under MIT license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgaunet%2Fpostgresql-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsgaunet%2Fpostgresql-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgaunet%2Fpostgresql-mcp/lists"}