{"id":26493949,"url":"https://github.com/dwarvesf/mcp-db","last_synced_at":"2025-07-10T19:04:13.462Z","repository":{"id":283272467,"uuid":"951036712","full_name":"dwarvesf/mcp-db","owner":"dwarvesf","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-02T06:52:54.000Z","size":869,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-02T07:49:09.584Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dwarvesf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-03-19T04:18:02.000Z","updated_at":"2025-05-02T06:52:58.000Z","dependencies_parsed_at":"2025-04-11T09:57:14.091Z","dependency_job_id":"423ea684-0144-4406-a099-aa195bda3394","html_url":"https://github.com/dwarvesf/mcp-db","commit_stats":null,"previous_names":["dwarvesf/mcp-db"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/dwarvesf/mcp-db","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwarvesf%2Fmcp-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwarvesf%2Fmcp-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwarvesf%2Fmcp-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwarvesf%2Fmcp-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dwarvesf","download_url":"https://codeload.github.com/dwarvesf/mcp-db/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwarvesf%2Fmcp-db/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264638201,"owners_count":23642121,"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","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":[],"created_at":"2025-03-20T09:58:22.206Z","updated_at":"2025-07-10T19:04:13.260Z","avatar_url":"https://github.com/dwarvesf.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Database Server\n\nA Model Context Protocol (MCP) server that provides tools for interacting with databases, including PostgreSQL, DuckDB, and Google Cloud Storage (GCS) Parquet files.\n\n## Prerequisites\n\n- Node.js 22 or higher\n- TypeScript\n- PostgreSQL (for PostgreSQL features)\n- Google Cloud credentials (optional, for read files from GCS)\n\n## Project Structure\n\n```plaintext\n.\n├── Makefile\n├── README.md\n├── docker-compose.yml\n├── docs\n│   ├── llm-full.md\n│   ├── requirements-mcp.md\n│   └── sdk.md\n├── migrations\n│   └── init.sql\n├── package-lock.json\n├── package.json\n├── src\n│   ├── config.ts\n│   ├── duckdb.ts\n│   ├── gcs.ts\n│   ├── handlers.ts\n│   ├── postgres.ts\n│   ├── server.ts\n│   ├── tools.ts\n│   ├── types.ts\n│   └── utils.ts\n└── tsconfig.json\n```\n\n## Installation\n\n1. Clone the repository:\n```bash\ngit clone \u003crepository-url\u003e\ncd mcp-db\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Build the project:\n```bash\nnpm run build\n```\n\n## Configuration\n\n### Environment Variables and CLI Arguments\n- `--database-url`: PostgreSQL connection string (required)\n- `--log-level`: Logging level (debug, info, error) (default: info)\n\n### GCS Authentication\nFor Google Cloud Storage, choose one method:\n1. Set the `GCP_SERVICE_ACCOUNT` environment variable with base64-encoded service account credentials\n2. Use default credentials (e.g., GKE Workload Identity)\n\n## Running the Server\n\n### Development Mode\n```bash\nnpm run dev\n```\n\n### Production Mode\n```bash\nnpm run build\nnpm start\n```\n\n### Example Configurations\n\n```bash\nnpm start -- --database-url \"postgresql://user:password@localhost:5432/mydb\"\n```\n\n## Available Tools\n\n### Database Tools\n- `sql_query_read`: Execute SELECT queries\n- `sql_query_create`: Execute CREATE/INSERT statements\n- `sql_query_update`: Execute UPDATE statements\n- `sql_query_delete`: Execute DELETE statements\n\n### DuckDB Tools\n- `duckdb_read_parquet_files`: Query Parquet files\n\n## Documentation\n\nAdditional documentation can be found in the `docs/` directory:\n- `docs/llm-full.md`: Comprehensive documentation\n- `docs/requirements-mcp.md`: MCP requirements\n- `docs/sdk.md`: SDK-related documentation\n\n## Development: Integrating a New Tool\n\nTo integrate a new tool into an MCP server, follow these key steps:\n\n### 1. Import Required Modules\n\n```typescript\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport {\n  CallToolRequestSchema,\n  ListToolsRequestSchema,\n  Tool,\n} from \"@modelcontextprotocol/sdk/types.js\";\n```\n\n### 2. Define Tool Interfaces and Definitions\n\n```typescript\n// Define an interface for tool arguments\ninterface MyToolArgs {\n  param1: string;\n  param2?: number;\n}\n\n// Create a tool definition with input schema\nconst myCustomTool: Tool = {\n  name: \"my_custom_tool\",\n  description: \"A description of what the tool does\",\n  inputSchema: {\n    type: \"object\",\n    properties: {\n      param1: {\n        type: \"string\",\n        description: \"Description of param1\"\n      },\n      param2: {\n        type: \"number\",\n        description: \"Optional description of param2\"\n      }\n    },\n    required: [\"param1\"]\n  }\n};\n```\n\n### 3. Set Up Server with Request Handlers\n\n```typescript\nconst server = new Server(\n  {\n    name: \"My MCP Server\",\n    version: \"1.0.0\"\n  },\n  {\n    capabilities: {\n      tools: {}\n    }\n  }\n);\n\n// Handle tool calls\nserver.setRequestHandler(\n  CallToolRequestSchema,\n  async (request) =\u003e {\n    switch (request.params.name) {\n      case \"my_custom_tool\": {\n        const args = request.params.arguments as MyToolArgs;\n        // Implement tool logic here\n        return {\n          content: [{ \n            type: \"text\", \n            text: JSON.stringify({ result: \"Tool execution result\" }) \n          }]\n        };\n      }\n      default:\n        throw new Error(`Unknown tool: ${request.params.name}`);\n    }\n  }\n);\n\n// List available tools\nserver.setRequestHandler(\n  ListToolsRequestSchema, \n  async () =\u003e ({\n    tools: [myCustomTool]\n  })\n);\n\n// Connect server to transport\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n### Best Practices\n\n- Always define clear input schemas for your tools\n- Handle errors gracefully\n- Use TypeScript for type safety\n- Implement comprehensive logging\n- Validate input arguments before processing\n\n### Environment Variables\n\nSensitive information like API keys should be passed via environment variables:\n\n```bash\nTOOL_API_KEY=your_secret_key npm start\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwarvesf%2Fmcp-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdwarvesf%2Fmcp-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwarvesf%2Fmcp-db/lists"}