{"_id":"@ahmedmustahid/postgres-mcp-server","_rev":"7-5e5d8fbb6889077f0e1b1bbcd4692ceb","name":"@ahmedmustahid/postgres-mcp-server","dist-tags":{"latest":"0.8.5"},"versions":{"0.8.3":{"name":"@ahmedmustahid/postgres-mcp-server","version":"0.8.3","keywords":["postgres","mcp","server","database","model-context-protocol"],"author":{"name":"Ahmed Mustahid"},"license":"MIT","_id":"@ahmedmustahid/postgres-mcp-server@0.8.3","maintainers":[{"name":"ahmedmustahid","email":"anabanana5506@gmail.com"}],"homepage":"https://modelcontextprotocol.io","bugs":{"url":"https://github.com/modelcontextprotocol/servers/issues"},"bin":{"postgres-mcp-server":"dist/src/cli.js"},"dist":{"shasum":"028246de0ef25154cfeb102ee6811abaa69145dc","tarball":"https://registry.npmjs.org/@ahmedmustahid/postgres-mcp-server/-/postgres-mcp-server-0.8.3.tgz","fileCount":16,"integrity":"sha512-5tpmDxlI5gQcdJWRyPDLLdvNU/D/+fNPD6T0Qq3M+sTKASdRe5Ev3rrP4BBU121k+1qK33UTqP/nV2c0h5P5vw==","signatures":[{"sig":"MEQCIHkfLoQUZyXUTvWM+moqcSuMzJz0SVJpRERHE8H+rxA2AiBJuGqafmfKU5f4d3/0pJjs3eXscqUR0oPkhhcvZFdigg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28571},"main":"dist/src/index.js","type":"module","engines":{"node":">=18.0.0"},"exports":{".":"./dist/src/index.js","./stdio":"./dist/src/stdioIndex.js"},"gitHead":"916c85dbff1e48b7222de3100f6dea59e6125ade","scripts":{"lint":"echo 'Linting not configured'","build":"tsc && shx chmod +x dist/src/*.js","clean":"rm -rf dist","watch":"tsc --watch","format":"echo 'Formatting not configured'","prepare":"npm run build","dev:http":"tsx src/index.ts","dev:stdio":"tsx src/stdioIndex.ts","docker:up":"docker-compose up -d mcp-http","start:http":"node dist/src/index.js","compose:dev":"docker-compose -f docker-compose.yml -f docker-compose.dev.yml up","docker:down":"docker-compose down","docker:logs":"docker-compose logs -f","start:stdio":"node dist/src/stdioIndex.js","docker:build":"docker-compose build","docker:clean":"docker-compose down -v --rmi all","prepublishOnly":"npm run build","docker:up:stdio":"docker-compose --profile stdio up mcp-stdio","docker:logs:http":"docker-compose logs -f mcp-http","docker:logs:stdio":"docker-compose logs -f mcp-stdio","docker:shell:http":"docker-compose exec mcp-http sh"},"_npmUser":{"name":"ahmedmustahid","actor":{"name":"ahmedmustahid","type":"user","email":"anabanana5506@gmail.com"},"email":"anabanana5506@gmail.com"},"repository":{"url":"git+https://github.com/ahmedmustahid/postgres-mcp-server.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server for interacting with PostgreSQL databases","directories":{},"_nodeVersion":"20.19.2","dependencies":{"pg":"^8.16.0","cors":"^2.8.5","dotenv":"^16.5.0","express":"^5.1.0","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.3.4","tsx":"^4.19.4","ts-node":"^10.9.2","@types/pg":"^8.11.10","typescript":"^5.8.3","@types/cors":"^2.8.18","@types/node":"^22.15.23","@types/express":"^5.0.2"},"_npmOperationalInternal":{"tmp":"tmp/postgres-mcp-server_0.8.3_1750566517733_0.6315682703310033","host":"s3://npm-registry-packages-npm-production"}},"0.8.4":{"name":"@ahmedmustahid/postgres-mcp-server","version":"0.8.4","keywords":["postgres","mcp","server","database","model-context-protocol"],"author":{"name":"Ahmed Mustahid"},"license":"MIT","_id":"@ahmedmustahid/postgres-mcp-server@0.8.4","maintainers":[{"name":"ahmedmustahid","email":"anabanana5506@gmail.com"}],"homepage":"https://modelcontextprotocol.io","bugs":{"url":"https://github.com/modelcontextprotocol/servers/issues"},"bin":{"postgres-mcp-server":"dist/src/cli.js"},"dist":{"shasum":"8df0c71871df46a2f5bff7cd9fd6b45776aa7277","tarball":"https://registry.npmjs.org/@ahmedmustahid/postgres-mcp-server/-/postgres-mcp-server-0.8.4.tgz","fileCount":16,"integrity":"sha512-1MlEA+2Uz3uBBf8ZJrklobtVoz0bWAoGSk+mBQqsSuJqW75iCRmzrrV1SDAzyXsQVx02tBO4YRtRGyxD3m+M1Q==","signatures":[{"sig":"MEQCIDfhQf1nUDoCCDzGAIYqRV+Vb8PQXcr2UOX807PnmTn9AiBkHtYlQiQHGe/cr6QcqsfivldZKZuUFoDJRX+INZGEaQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28529},"main":"dist/src/index.js","type":"module","engines":{"node":">=18.0.0"},"exports":{".":"./dist/src/index.js","./stdio":"./dist/src/stdioIndex.js"},"gitHead":"04f8611c3302595523b2255ffbb7370894761a3b","scripts":{"lint":"echo 'Linting not configured'","build":"tsc && shx chmod +x dist/src/*.js","clean":"rm -rf dist","watch":"tsc --watch","format":"echo 'Formatting not configured'","prepare":"npm run build","dev:http":"tsx src/index.ts","dev:stdio":"tsx src/stdioIndex.ts","docker:up":"docker-compose up -d mcp-http","start:http":"node dist/src/index.js","compose:dev":"docker-compose -f docker-compose.yml -f docker-compose.dev.yml up","docker:down":"docker-compose down","docker:logs":"docker-compose logs -f","start:stdio":"node dist/src/stdioIndex.js","docker:build":"docker-compose build","docker:clean":"docker-compose down -v --rmi all","prepublishOnly":"npm run build","docker:up:stdio":"docker-compose --profile stdio up mcp-stdio","docker:logs:http":"docker-compose logs -f mcp-http","docker:logs:stdio":"docker-compose logs -f mcp-stdio","docker:shell:http":"docker-compose exec mcp-http sh"},"_npmUser":{"name":"ahmedmustahid","actor":{"name":"ahmedmustahid","type":"user","email":"anabanana5506@gmail.com"},"email":"anabanana5506@gmail.com"},"repository":{"url":"git+https://github.com/ahmedmustahid/postgres-mcp-server.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server for interacting with PostgreSQL databases","directories":{},"_nodeVersion":"20.19.2","dependencies":{"pg":"^8.16.0","cors":"^2.8.5","dotenv":"^16.5.0","express":"^5.1.0","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.3.4","tsx":"^4.19.4","ts-node":"^10.9.2","@types/pg":"^8.11.10","typescript":"^5.8.3","@types/cors":"^2.8.18","@types/node":"^22.15.23","@types/express":"^5.0.2"},"_npmOperationalInternal":{"tmp":"tmp/postgres-mcp-server_0.8.4_1750662861419_0.714280396808997","host":"s3://npm-registry-packages-npm-production"}},"0.8.5":{"name":"@ahmedmustahid/postgres-mcp-server","version":"0.8.5","description":"MCP server for interacting with PostgreSQL databases","license":"MIT","author":{"name":"Ahmed Mustahid"},"engines":{"node":">=18.0.0"},"homepage":"https://modelcontextprotocol.io","bugs":{"url":"https://github.com/modelcontextprotocol/servers/issues"},"publishConfig":{"access":"public"},"keywords":["postgres","mcp","server","database","model-context-protocol"],"exports":{".":"./dist/src/index.js","./stdio":"./dist/src/stdioIndex.js"},"type":"module","bin":{"postgres-mcp-server":"dist/src/cli.js"},"scripts":{"build":"tsc && shx chmod +x dist/src/*.js","prepublishOnly":"npm run build","prepare":"npm run build","watch":"tsc --watch","clean":"rm -rf dist","dev:http":"tsx src/index.ts","dev:stdio":"tsx src/stdioIndex.ts","start:http":"node dist/src/index.js","start:stdio":"node dist/src/stdioIndex.js","docker:build":"docker-compose build","docker:up":"docker-compose up -d mcp-http","docker:up:stdio":"docker-compose --profile stdio up mcp-stdio","docker:down":"docker-compose down","docker:logs":"docker-compose logs -f","docker:logs:http":"docker-compose logs -f mcp-http","docker:logs:stdio":"docker-compose logs -f mcp-stdio","docker:shell:http":"docker-compose exec mcp-http sh","docker:clean":"docker-compose down -v --rmi all","compose:dev":"docker-compose -f docker-compose.yml -f docker-compose.dev.yml up","lint":"echo 'Linting not configured'","format":"echo 'Formatting not configured'"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","cors":"^2.8.5","dotenv":"^16.5.0","express":"^5.1.0","pg":"^8.16.0"},"devDependencies":{"@types/cors":"^2.8.18","@types/express":"^5.0.2","@types/node":"^22.15.23","@types/pg":"^8.11.10","shx":"^0.3.4","ts-node":"^10.9.2","tsx":"^4.19.4","typescript":"^5.8.3"},"main":"dist/src/index.js","repository":{"type":"git","url":"git+https://github.com/ahmedmustahid/postgres-mcp-server.git"},"_id":"@ahmedmustahid/postgres-mcp-server@0.8.5","gitHead":"039ce5c88edcdc03c2e90c41f3e6708c4e557523","_nodeVersion":"20.19.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-huJYt1K0t6cxts60ij7EeMpwWYYEQEu/5/mf8ARWvZnaqbLBvW6zhVkSej9qM6LMLMeg2mfEmMYJydOrA9g4Zg==","shasum":"afe9d20cbdea83a288be5007cdd9909683efa4de","tarball":"https://registry.npmjs.org/@ahmedmustahid/postgres-mcp-server/-/postgres-mcp-server-0.8.5.tgz","fileCount":16,"unpackedSize":28877,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD5kQYbqzrXWs6ovoPj4cuBiokL/jpJ+XrOGBR4HrQnfAIhAPQdy/Wb6P+XZtkve8HJnUVjdpdicSWm0vS9PcIp6Wdb"}]},"_npmUser":{"name":"ahmedmustahid","email":"anabanana5506@gmail.com"},"directories":{},"maintainers":[{"name":"ahmedmustahid","email":"anabanana5506@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/postgres-mcp-server_0.8.5_1752485279371_0.42716784587974255"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-23T07:14:21.291Z","modified":"2025-07-14T09:27:59.762Z","0.8.0":"2025-06-21T12:15:18.172Z","0.8.1":"2025-06-21T12:51:03.622Z","0.8.2":"2025-06-21T13:25:32.271Z","0.8.3":"2025-06-22T04:28:37.918Z","0.8.4":"2025-06-23T07:14:21.626Z","0.8.5":"2025-07-14T09:27:59.566Z"},"bugs":{"url":"https://github.com/modelcontextprotocol/servers/issues"},"author":{"name":"Ahmed Mustahid"},"license":"MIT","homepage":"https://modelcontextprotocol.io","keywords":["postgres","mcp","server","database","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/ahmedmustahid/postgres-mcp-server.git"},"description":"MCP server for interacting with PostgreSQL databases","maintainers":[{"name":"ahmedmustahid","email":"anabanana5506@gmail.com"}],"readme":"# MCP PostgreSQL Server (Stateful and Dual Transport)\n\nA Model Context Protocol (MCP) server that provides both HTTP and Stdio transports for interacting with PostgreSQL databases. This server exposes database resources and tools through both transport methods, allowing for flexible integration in different environments.\n\n## Features\n\n- **Dual Transport Support**: Both HTTP (StreamableHTTPServerTransport) and Stdio (StdioServerTransport)\n- **Database Resources**: List tables and retrieve schema information\n- **Query Tool**: Execute read-only SQL queries\n- **Stateful Sessions**: HTTP transport supports session management\n- **Docker Support**: Containerized deployments for both transports\n- **Production Ready**: Graceful shutdown, error handling, and logging\n\n## Quick Start\n### Environment Setup\n\nThe database credentials must be passed as:\n\n1. Either environment variables\n```bash\n# PostgreSQL Database Connection String\nexport POSTGRES_URL=your_connection_string\n\n# PostgreSQL Database Configuration if POSTGRES_URL is not provided\nexport POSTGRES_USERNAME=your_username\nexport POSTGRES_PASSWORD=your_password\nexport POSTGRES_HOST=localhost\nexport POSTGRES_PORT=5432 # this is the default\nexport POSTGRES_DATABASE=your_database\n\n# HTTP Server Configuration\n# Following are the default values\nexport PORT=3000\nexport HOST=0.0.0.0\n\n# CORS Configuration (comma-separated list of allowed origins)\n# Following are the default values\nexport CORS_ORIGIN=http://localhost:8080,http://localhost:3000\n\n# Environment\n# Following are the default values\nexport NODE_ENV=development\n\n```\n2. Or in the working directory (directory where `npx` command will be run):\ncreate a `.env` file (the package uses `dotenv` package)\n\n```bash\n# .env.example\n# PostgreSQL Database Configuration\nPOSTGRES_USERNAME=your_username\nPOSTGRES_PASSWORD=your_password\nPOSTGRES_HOST=localhost\nPOSTGRES_DATABASE=your_database\n\n# HTTP Server Configuration\nPORT=3000\nHOST=0.0.0.0\n\n# CORS Configuration (comma-separated list of allowed origins)\nCORS_ORIGIN=http://localhost:8080,http://localhost:3000\n\n# Environment\nNODE_ENV=development\n```\n\n### Run using `npx`\n\n1. Download node.js and npm from [here](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)\n2. Run the package. By default, it will run streamable http on port 3000:\n```bash\nnpx @ahmedmustahid/postgres-mcp-server\n# or npx @ahmedmustahid/postgres-mcp-server --port 3000 --verbose\n```\n3. For stdio transport:\n```bash\nnpx @ahmedmustahid/postgres-mcp-server stdio\n# npx @ahmedmustahid/postgres-mcp-server stdio --verbose\n```\n\n### Environment Setup\n\nCopy environment template\n```bash\ncp .env.example .env\n```\n\nEdit your database credentials\n```bash\nnano .env\n```\n\n## Podman(or Docker) Usage\n\n1. Install podman from [here](https://podman.io/docs/installation)\n2. Install `uv` from [here](https://docs.astral.sh/uv/getting-started/installation/)\n3. Install podman compose package: `uv add podman-compose` (or `uv sync` to sync packages in `pyproject.toml`)\n```bash\n#get the environment variables\nset -a\nsource .env\nset +a\npodman machine start\nmake podman-up\n```\n## Test using Claude Desktop\n\nFirst, install node.js and npm, build the project following the above instructions.\nEdit your `claude_desktop_config.json`\n```json\n{\n  \"mcpServers\": {\n    \"postgres-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@ahmedmustahid/postgres-mcp-server\",\n        \"stdio\"\n      ],\n      \"env\": {\n        \"POSTGRES_USERNAME\": \"your-username\",\n        \"POSTGRES_PASSWORD\": \"your-password\",\n        \"POSTGRES_HOST\": \"hostname\",\n        \"POSTGRES_DATABASE\": \"database-name\"\n      }\n    }\n  }\n}\n```\n#### Check if MCP Server has been enabled\n\nVerify from Claude Desktop Window\n\n![Claude Desktop Window](images/cd_window.png)\n\n#### Using MCP Server from Claude Desktop\n\nPrompt: Show `sales` table from last year.\n\n![Result](images/cd_mcp.png)\n\n\n### Test using MCP Inspector\n\nFirst, install node.js and npm, build the project following the above instructions.\nInstall MCP Inspector: instructions: [here](https://modelcontextprotocol.io/docs/tools/inspector)\n\n#### Check Stdio MCP Server\n```bash\nnpx @modelcontextprotocol/inspector npx @ahmedmustahid/postgres-mcp-server stdio\n```\n![Stdio in MCP Inspector](images/mcp_insp_stdio.png)\n\n#### Check Streamable HTTP MCP Server\n\nFirst, run the server (shell where environment has been configured):\n```bash\nnpx @ahmedmustahid/postgres-mcp-server\n```\nRun the mcp inspector from another terminal\n```bash\nnpx @modelcontextprotocol/inspector\n```\nAfter selecting `Streamable HTTP` from drop down menu, insert `http://localhost:3000/mcp`(default) into URL.\n\nMCP tools:\n![MCP Tools in MCP Inspector](images/http_tool.png)\n\nMCP Resource:\n![MCP Resource in MCP Inspector](images/http_resource.png)\n\n\n## Configuration\n\n### Environment Variables\n\nYou have to specify these inside the .env file.\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `POSTGRES_USERNAME` | PostgreSQL username | - | Yes |\n| `POSTGRES_PASSWORD` | PostgreSQL password | - | Yes |\n| `POSTGRES_HOST` | PostgreSQL host | - | Yes |\n| `POSTGRES_DATABASE` | PostgreSQL database name | - | Yes |\n| `PORT` | HTTP server port | 3000 | No |\n| `HOST` | HTTP server host | 0.0.0.0 | No |\n| `CORS_ORIGIN` | Allowed CORS origins (comma-separated) | localhost:8080,localhost:3000 | No |\n| `NODE_ENV` | Environment mode | development | No |\n\n\n## Resources\n\n### Hello World (`hello://world`)\nA simple greeting message for testing.\n\n### Database Tables (`database://tables`)\nLists all tables in the public schema with their schema URIs.\n\n### Database Schema (`database://tables/{tableName}/schema`)\nReturns column information for a specific table.\n\n## Tools\n\n### query\nExecute read-only SQL queries against the database.\n\n**Parameters:**\n- `sql` (string): The SQL query to execute\n\n\n## Transport Differences\n\n| Feature | HTTP Transport | Stdio Transport |\n|---------|----------------|-----------------|\n| Session Management | ✅ Stateful sessions | ❌ Stateless |\n| Concurrent Connections | ✅ Multiple clients | ❌ Single process |\n| Web Integration | ✅ REST API compatible | ❌ CLI only |\n| Interactive Use | ✅ Via HTTP clients | ✅ Direct stdio |\n| Docker Deployment | ✅ Web service | ✅ CLI container |\n\n## Health Checks\n\nThe HTTP server includes a basic health check endpoint accessible at the `/health` endpoint with a GET request (returns 405 Method Not Allowed, confirming the server is responsive).\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Database Connection Errors**\n   ```bash\n   # Check your database credentials in .env\n   # Ensure PostgreSQL is running and accessible\n   ```\n\n2. **Port Already in Use**\n   ```bash\n   # Change PORT in .env or stop conflicting services\n   lsof -i :3000\n   ```\n\n3. **Docker Build Issues**\n   ```bash\n   # Clean Docker cache\n   npm run docker:clean\n   docker system prune -a\n   ```\n\n4. **Session Management (HTTP)**\n   ```bash\n   # Sessions are stored in memory and will reset on server restart\n   # For production, consider implementing persistent session storage\n   ```\n\n## Development\n\n### Adding New Resources\n\n1. Create a new file in `src/resources/`\n2. Implement the resource registration function\n3. Add it to `src/server/server.ts`\n\n### Adding New Tools\n\n1. Create a new file in `src/tools/`\n2. Implement the tool registration function\n3. Add it to `src/server/server.ts`\n\n## License\n\nMIT\n\n## Contributing\n\nPlease read the contributing guidelines and submit pull requests to the main repository.\n","readmeFilename":"README.md"}