{
  "markdown": "<!-- mcp-name: io.github.musaddiq-dev/postgresql-mcp-server -->\n# PostgreSQL MCP Server\n\nA Python Model Context Protocol (MCP) server for inspecting and querying PostgreSQL databases from MCP-compatible clients. It provides schema discovery, safe read-only query execution, query explanation, table previews, index analysis, relationship inspection, and PostgreSQL resources for table metadata.\n\n## Features\n\n- List public tables and inspect table schemas\n- Execute read-only SQL in a PostgreSQL read-only transaction\n- Explain query plans without executing the target query directly\n- Preview table rows with a fixed limit\n- Inspect foreign-key relationships and indexes\n- Expose passive MCP resources for table lists and schema details\n\n## Safety Model\n\n`postgresql_execute_read_query` runs with PostgreSQL read-only transaction mode, caps returned rows by `POSTGRES_READ_QUERY_LIMIT`, and rolls back after execution. The server also includes `postgresql_execute_write_query`, which only accepts a single INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, or TRUNCATE statement and can modify data/schema if the connected database user has permission. Do not auto-approve write-capable tools in your MCP client. For public or shared use, run the server with a dedicated read-only PostgreSQL user.\n\n## Requirements\n\n- Python 3.11+\n- PostgreSQL database\n- MCP-compatible client such as Claude Desktop, Cursor, VS Code, or another MCP host\n\n## Installation\n\nWhen published to PyPI, install or run the server like a standard Python MCP package:\n\n```bash\nuvx mdev-postgresql-mcp-server\n```\n\nFor local development from source:\n\n```bash\ngit clone https://github.com/musaddiq-dev/postgresql-mcp-server.git\ncd postgresql-mcp-server\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n```\n\n## Configuration\n\nCopy the example environment file and update it with your database connection details.\n\n```bash\ncp .env.example .env\n```\n\n| Variable | Description | Required | Default |\n| --- | --- | --- | --- |\n| `POSTGRES_HOST` | PostgreSQL host | Yes | `localhost` |\n| `POSTGRES_PORT` | PostgreSQL port | Yes | `5432` |\n| `POSTGRES_USER` | PostgreSQL username | Yes | None |\n| `POSTGRES_PASSWORD` | PostgreSQL password | No | None |\n| `POSTGRES_DB` | PostgreSQL database name | Yes | None |\n| `LOG_LEVEL` | Python logging level written to stderr | No | `INFO` |\n| `POSTGRES_READ_QUERY_LIMIT` | Maximum rows returned by read queries | No | `1000` |\n\nExample read-only user:\n\n```sql\nCREATE USER mcp_readonly WITH PASSWORD 'change-me';\nGRANT CONNECT ON DATABASE your_database TO mcp_readonly;\nGRANT USAGE ON SCHEMA public TO mcp_readonly;\nGRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;\nALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;\n```\n\n## Running\n\n```bash\nmdev-postgresql-mcp-server\n```\n\nFrom a local checkout before PyPI publication, run:\n\n```bash\npython -m postgresql_mcp_server.server\n```\n\n## MCP Client Configuration\n\nFor published installs, prefer `uvx`. MCP servers using stdio must write protocol messages only to stdout; this server writes logs to stderr through Python logging.\n\n### Claude Desktop / Cursor / Windsurf / Cline\n\nMost MCP clients accept this `mcpServers` JSON shape:\n\n```json\n{\n  \"mcpServers\": {\n    \"postgresql\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mdev-postgresql-mcp-server\"],\n      \"env\": {\n        \"POSTGRES_HOST\": \"localhost\",\n        \"POSTGRES_PORT\": \"5432\",\n        \"POSTGRES_USER\": \"mcp_readonly\",\n        \"POSTGRES_PASSWORD\": \"change-me\",\n        \"POSTGRES_DB\": \"your_database\"\n      }\n    }\n  }\n}\n```\n\nFor local development from this repository, use the installed console script path instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"postgresql\": {\n      \"command\": \"/absolute/path/to/postgresql-mcp-server/.venv/bin/mdev-postgresql-mcp-server\",\n      \"args\": [],\n      \"env\": {\n        \"POSTGRES_HOST\": \"localhost\",\n        \"POSTGRES_PORT\": \"5432\",\n        \"POSTGRES_USER\": \"mcp_readonly\",\n        \"POSTGRES_PASSWORD\": \"change-me\",\n        \"POSTGRES_DB\": \"your_database\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code CLI\n\n```bash\nclaude mcp add postgresql \\\n  --env POSTGRES_HOST=localhost \\\n  --env POSTGRES_PORT=5432 \\\n  --env POSTGRES_USER=mcp_readonly \\\n  --env POSTGRES_PASSWORD=change-me \\\n  --env POSTGRES_DB=your_database \\\n  -- uvx mdev-postgresql-mcp-server\n```\n\n### VS Code MCP\n\nVS Code uses the same command/args/env model in its MCP configuration:\n\n```json\n{\n  \"servers\": {\n    \"postgresql\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"mdev-postgresql-mcp-server\"],\n      \"env\": {\n        \"POSTGRES_HOST\": \"localhost\",\n        \"POSTGRES_PORT\": \"5432\",\n        \"POSTGRES_USER\": \"mcp_readonly\",\n        \"POSTGRES_PASSWORD\": \"change-me\",\n        \"POSTGRES_DB\": \"your_database\"\n      }\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | Purpose | Safety |\n| --- | --- | --- |\n| `postgresql_list_tables` | List public base tables | Read-only |\n| `postgresql_describe_table` | Show columns and metadata for a table | Read-only |\n| `postgresql_execute_read_query` | Run bounded SQL under read-only transaction mode | Read-only |\n| `postgresql_execute_write_query` | Run a single approved modifying SQL statement and commit | Destructive |\n| `postgresql_explain_query` | Return PostgreSQL `EXPLAIN` output for a single query | Read-only |\n| `postgresql_get_database_summary` | Return database version and table count | Read-only |\n| `postgresql_get_relationships` | Inspect foreign-key relationships | Read-only |\n| `postgresql_analyze_indexes` | Inspect indexes and sizes | Read-only |\n| `postgresql_preview_table` | Return up to 10 rows from a table | Read-only |\n| `postgresql_search_sql_definitions` | Search public SQL routines/functions | Read-only |\n\n## Resources\n\n- `postgres://list_tables` returns public table names.\n- `postgres://schema/{table_name}` returns a generated schema statement for a table.\n\n## Smoke Check\n\nWithout a database, verify syntax with:\n\n```bash\npython -m py_compile src/postgresql_mcp_server/server.py\n```\n\nWith a configured database, start the server and use your MCP client to call `list_tables`.\n\n## Distribution\n\nThis server is published through the standard Python MCP distribution path:\n\n- PyPI package: [`mdev-postgresql-mcp-server`](https://pypi.org/project/mdev-postgresql-mcp-server/)\n- MCP Registry name: `io.github.musaddiq-dev/postgresql-mcp-server`\n- Runtime hint: `uvx`\n- Transport: `stdio`\n\nThe `mcp-name` marker at the top of this README is required for MCP Registry ownership verification. Users should prefer `uvx mdev-postgresql-mcp-server` in local MCP client configurations.\n\n## Security Notes\n\n- Do not commit `.env` or MCP client configs containing credentials.\n- Use least-privilege database users.\n- Treat `execute_write_query` as destructive and require explicit user approval in your MCP client.\n- Review generated SQL before running write-capable tools.\n\n## License\n\nMIT\n",
  "bytes": 6914,
  "sha": "84722e2bc8a7f39f557258adafdf27aa07b70bc67d790e32010a8eeee1916214",
  "repo_slug": "musaddiq-dev/postgresql-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_musaddiq_dev_postgresql_mcp_se_b98c2d3a/readme"
}