{"id":33837723,"url":"https://github.com/wenb1n-dev/SmartDB_MCP","last_synced_at":"2025-12-12T23:00:56.629Z","repository":{"id":311749254,"uuid":"1039083002","full_name":"wenb1n-dev/SmartDB_MCP","owner":"wenb1n-dev","description":"Universal database MCP server connecting to MySQL, PostgreSQL, SQL Server, MariaDB,DM8,Oracle,not only provides basic database connection such as OAuth 2.0 authentication , health checks, SQL optimization, and index health detection","archived":false,"fork":false,"pushed_at":"2025-09-14T04:37:20.000Z","size":319,"stargazers_count":89,"open_issues_count":6,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-27T20:14:46.586Z","etag":null,"topics":["ai","dameng8","dify","mcp","mcp-server","mysql","oauth2","oracle","postgresql","sqlserver"],"latest_commit_sha":null,"homepage":"","language":"Python","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/wenb1n-dev.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2025-08-16T12:51:33.000Z","updated_at":"2025-11-27T20:06:14.000Z","dependencies_parsed_at":"2025-08-26T12:04:07.881Z","dependency_job_id":"a1ae21eb-2b7a-4018-bfe7-538c4d5f4b56","html_url":"https://github.com/wenb1n-dev/SmartDB_MCP","commit_stats":null,"previous_names":["wenb1n-dev/smartdb_mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/wenb1n-dev/SmartDB_MCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wenb1n-dev%2FSmartDB_MCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wenb1n-dev%2FSmartDB_MCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wenb1n-dev%2FSmartDB_MCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wenb1n-dev%2FSmartDB_MCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wenb1n-dev","download_url":"https://codeload.github.com/wenb1n-dev/SmartDB_MCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wenb1n-dev%2FSmartDB_MCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27694440,"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-12-12T02:00:06.775Z","response_time":129,"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","dameng8","dify","mcp","mcp-server","mysql","oauth2","oracle","postgresql","sqlserver"],"created_at":"2025-12-07T23:00:35.442Z","updated_at":"2025-12-12T23:00:56.610Z","avatar_url":"https://github.com/wenb1n-dev.png","language":"Python","funding_links":[],"categories":["Databases","Database \u0026 Messaging Mcp Servers","サーバー実装","📚 Projects (2474 total)","🗄️ Database"],"sub_categories":["SQL Databases","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eデータベース","MCP Servers"],"readme":"[![简体中文](https://img.shields.io/badge/简体中文-点击查看-orange)](README-zh.md)\n[![English](https://img.shields.io/badge/English-Click-yellow)](README.md)\n\n\u003cimg width=\"1023\" height=\"270\" alt=\"image\" src=\"https://github.com/user-attachments/assets/4b282174-dd45-4edb-9de8-9b14e2c59a9e\" /\u003e\n\n# SmartDB\n## 好用就帮忙点个赞，支持一下呀，拜托各位精英们～。\nSmartDB是一个通用数据库网关，实现了模型上下文协议（Model Context Protocol，简称MCP）服务器接口。这个网关允许与MCP兼容的客户端连接并探索不同的数据库。\n\n与同类产品相比，SmartDB不仅提供基本的数据库连接和探索功能，还增加了OAuth2.0认证、健康检查、SQL优化和索引健康检测等高级功能，使数据库管理和维护更加安全、智能化。\n\n\u003cimg width=\"1303\" height=\"697\" alt=\"image\" src=\"https://github.com/user-attachments/assets/9340f85e-28b0-45f2-8cb2-768b0d1c8b5c\" /\u003e\n\n\n# 目前支持的数据库\n| 数据库 | 支持 | 描述                          |\n|-----|----|-----------------------------|\n| MySQL | √  | Mysql 5.6+、Mariadb 10+ 均支持  |\n| PostgreSQL | √  | PostgreSQL 9.6+、YMatrix 均支持 |\n| Oracle | √  | Oracle 12 +                 |\n| SQL Server | √  | Microsoft SQL Server 2012 + |\n| 达梦数据库 | √  | DM8                         |\n\n# 工具列表\n| 工具名称            | 描述                                                                                                                                 |\n|-----------------|------------------------------------------------------------------------------------------------------------------------------------| \n| execute_sql     | sql执行工具，根据权限配置可执行[\"SELECT\", \"SHOW\", \"DESCRIBE\", \"EXPLAIN\", \"INSERT\", \"UPDATE\", \"DELETE\", \"CREATE\", \"ALTER\", \"DROP\", \"TRUNCATE\"] 命令 |\n| get_db_health   | 分析数据库的健康状态（连接情况、事务情况、运行情况、锁情况检测），输出专业的诊断报告及解决方案                                                                                    |\n| get_table_desc  | 根据表名搜索数据库中对应的表结构,支持多表查询                                                                                                            |\n| get_table_index | 根据表名搜索数据库中对应的表索引,支持多表查询                                                                                                            |\n| get_table_name  | 数据库表名查询工具。用于查询数据库中的所有表名或将根据表的中文名称或表描述搜索数据库中对应的表名                                                                                   |\n| get_db_version  | 数据库版本查询工具                                                                                                                          |\n| sql_creator     | SQL查询生成工具，根据不同的数据库类型生成对应SQL查询语句                                                                                                    \n| sql_optimize    | 专业的SQL性能优化工具，基于执行计划、表结构信息、表数据量、表索引提供专家级优化建议                                                                                        | \n\n# 使用方法\n## env 配置文件说明\n```aiignore\n# 数据库配置文件路径\nDATABASE_CONFIG_FILE=/Volumes/SmartDB/src/config/database_config.json\n\n#========OAuth2========\n# OAuth2 客户端 ID\nCLIENT_ID=smart_db_client_id\n# OAuth2 客户端密钥\nCLIENT_SECRET=smart_db_client_secret\n# 访问令牌过期时间（分钟）\nACCESS_TOKEN_EXPIRE_MINUTES=30\n# 刷新令牌过期时间（天）\nREFRESH_TOKEN_EXPIRE_DAYS=30\n# 令牌加密密钥\nTOKEN_SECRET_KEY=smart_db_token_secret\n# 用户名\nOAUTH_USER_NAME=admin\n# 密码\nOAUTH_USER_PASSWORD=wenb1n\n```\n\n注意：若调整了oauth配置中客户端的id以及密钥，请同时修改前段代码中static/config文件中的对应配置\n\n\n## 数据库连接配置说明\n```json\n{\n  \"default\": {\n    \"host\": \"192.168.xxx.xxx\",\n    \"port\": 3306,\n    \"user\": \"root\",\n    \"password\": \"root\",\n    \"database\": \"a_llm\",\n    \"role\": \"readonly\",\n    \"pool_size\": 10,\n    \"max_overflow\": 20,\n    \"pool_recycle\": 3600,\n    \"pool_timeout\": 30,\n    \"type\": \"mysql\"\n  },\n  \"postgresql\": {\n    \"host\": \"192.168.xxx.xxx\",\n    \"port\": 5432,\n    \"user\": \"postgres\",\n    \"password\": \"123456\",\n    \"database\": \"postgres\",\n    \"schema\": \"public\",\n    \"role\": \"readonly\",\n    \"pool_size\": 5,\n    \"max_overflow\": 10,\n    \"pool_recycle\": 3600,\n    \"pool_timeout\": 30,\n    \"type\": \"postgresql\"\n  },\n  \"oracle\": {\n    \"host\": \"192.168.xxx.xxx\",\n    \"port\": 1521,\n    \"user\": \"U_ORACLE\",\n    \"password\": \"123456\",\n    \"database\": \"123456\",\n    \"service_name\": \"ORCL\",\n    \"role\": \"readonly\",\n    \"pool_size\": 5,\n    \"max_overflow\": 10,\n    \"pool_recycle\": 3600,\n    \"pool_timeout\": 30,\n    \"type\": \"oracle\"\n  },\n  \"mssql\": {\n    \"host\": \"192.168.xxx.xxx\",\n    \"port\": 1433,\n    \"user\": \"test\",\n    \"password\": \"123456\",\n    \"database\": \"TEST\",\n    \"schema\": \"dbo\",\n    \"role\": \"readonly\",\n    \"pool_size\": 5,\n    \"max_overflow\": 10,\n    \"pool_recycle\": 3600,\n    \"pool_timeout\": 30,\n    \"type\": \"mssqlserver\"\n  }\n}\n\n```\n* 数据库连接参数说明\n\n下表详细说明了数据库连接配置文件中各参数的含义和用法：\n\n| 参数名 | 必需 | 类型 | 描述 |\n|--------|------|------|------|\n| host | 是 | string | 数据库服务器地址 |\n| port | 是 | integer | 数据库服务器端口号 |\n| user | 是 | string | 数据库用户名 |\n| password | 是 | string | 数据库用户密码 |\n| database | 是 | string | 要连接的数据库名称 |\n| role | 是 | string | 用户角色，如 \"readonly\" 表示只读权限 |\n| pool_size | 是 | integer | 连接池大小 |\n| max_overflow | 是 | integer | 连接池最大溢出连接数 |\n| pool_recycle | 是 | integer | 连接池回收时间（秒） |\n| pool_timeout | 是 | integer | 连接池超时时间（秒） |\n| type | 是 | string | 数据库类型，如 \"mysql\"、\"postgresql\"、\"oracle\"、\"mssqlserver\" |\n\n* 特定数据库额外参数\n\n| 参数名 | 数据库类型 | 必需 | 类型 | 描述 |\n|--------|------------|------|------|------|\n| schema | PostgreSQL, SQL Server | 否 | string | 数据库模式 |\n| service_name | Oracle | 否 | string | Oracle服务名 |\n\n* role 权限控制配置项以及对应数据库权限：只读（readonly）、读写（writer）、管理员（admin）\n```\n    \"readonly\": [\"SELECT\", \"SHOW\", \"DESCRIBE\", \"EXPLAIN\"],  # 只读权限\n    \"writer\": [\"SELECT\", \"SHOW\", \"DESCRIBE\", \"EXPLAIN\", \"INSERT\", \"UPDATE\", \"DELETE\"],  # 读写权限\n    \"admin\": [\"SELECT\", \"SHOW\", \"DESCRIBE\", \"EXPLAIN\", \"INSERT\", \"UPDATE\", \"DELETE\", \n             \"CREATE\", \"ALTER\", \"DROP\", \"TRUNCATE\"]  # 管理员权限\n```\n   \n* 注意\n\ndefault 为默认数据库连接配置，必须配置，其他数据库配置请自行添加 \n\n## pip安装和配置\n1. 安装包\n```bash\npip install SmartDB-MCP\n\n参数说明\n--mode：传输模式（“stdio”，“sse”，“streamablehttp”）\n--envfile 环境变量文件路径\n--oauth 启用 oauth 认证（目前仅支持“streamablehttp”模式）\n\n启动命令：\n smartdb --envfile=/Volumes/config/.env --oauth=true\n\n```\n\n## docker 启动\n### 快速开始\n\n#### 1. 构建并启动服务\n\n```bash\n# 修改自己的数据库连接配置文件路径\n修改[docker-compose.yml] 中\n    volumes:\n      - 你的外部database_config.json地址:/app/config/database_config.json\n\n# 使用docker-compose启动服务\ndocker-compose up -d\n\n# 查看服务状态\ndocker-compose ps\n\n# 查看日志\ndocker-compose logs -f smartdb\n```\n\n#### 2. 手动构建镜像\n\n```bash\n# 构建镜像\ndocker build -t smartdb-mcp:latest .\n\n# 运行容器\ndocker run -d \\\n  --name smartdb-mcp-server \\\n  -p 3000:3000 \\\n  -e DATABASE_CONFIG_FILE=/app/src/config/database_config.json \\\n  -e CLIENT_ID=smart_db_client_id \\\n  -e CLIENT_SECRET=smart_db_client_secret \\\n  -e TOKEN_SECRET_KEY=your_secret_key \\\n  -v $(pwd)/src/config:/app/src/config:ro \\\n  -v $(pwd)/logs:/app/logs \\\n  smartdb-mcp:latest\n```\n\n## 代码启动\n\n### 本地开发 Streamable Http 方式\n\n- 使用 uv 启动服务\n\n将以下内容添加到你的 mcp client 工具中，例如cursor、cline等\n\nmcp json 如下\n````\n{\n  \"mcpServers\": {\n    \"smartdb\": {\n      \"name\": \"smartdb\",\n      \"type\": \"streamableHttp\",\n      \"description\": \"\",\n      \"isActive\": true,\n      \"url\": \"http://localhost:3000/mcp/\"\n    }\n  }\n}\n````\n\n启动命令\n```\n# 下载依赖\nuv sync\n\n# 启动\nuv run -m core.server\n\n# 自定义env文件位置\nuv run -m core.server --envfile /path/to/.env\n```\n\n### 本地开发 SSE 方式\n\n- 使用 uv 启动服务\n\n将以下内容添加到你的 mcp client 工具中，例如cursor、cline等\n\nmcp json 如下\n````\n{\n  \"mcpServers\": {\n    \"smartdb\": {\n      \"name\": \"smartdb\",\n      \"description\": \"\",\n      \"isActive\": true,\n      \"url\": \"http://localhost:3000/sse\"\n    }\n  }\n}\n````\n\n启动命令\n```\n# 下载依赖\nuv sync\n\n# 启动\nuv run -m core.server --mode sse\n\n# 自定义env文件位置\nuv run -m core.server --mode sse --envfile /path/to/.env\n```\n\n### 本地开发 STDIO 方式 \n\n将以下内容添加到你的 mcp client 工具中，例如cursor、cline等\n\nmcp json 如下\n```\n{\n  \"mcpServers\": {\n      \"smartdb\": {\n          \"name\": \"smartdb\",\n          \"type\": \"stdio\",\n          \"isActive\": false,\n          \"registryUrl\": \"\",\n          \"command\": \"uv\",\n          \"args\": [\n            \"--directory\",\n            \"/Volumes/python/SmartDB/\",\n            \"run\",\n            \"-m\",\n            \"core.server\",\n            \"--mode\",\n            \"stdio\"\n          ],\n          \"env\": {\n            \"DATABASE_CONFIG_FILE\": \"/Volumes/database_config.json\"\n          }\n      }\n    }\n  }\n}  \n```\n\n## 支持OAuth 2.0 认证\n1. 启动认证服务,默认使用自带的OAuth 2.0 密码模式认证，可以在env中修改自己的认证服务地址\n```aiignore\nuv run -m core.server --oauth=true\n```\n\n2. 访问 认证服务 http://localhost:3000/login ，默认帐号密码在 env 中配置\n\u003cimg width=\"1777\" height=\"950\" alt=\"image\" src=\"https://github.com/user-attachments/assets/20531bee-467f-4758-bc08-fddc086ed411\" /\u003e\n\n\n3. 复制 token ，将token 添加在请求头中，例如\n\u003cimg width=\"1838\" height=\"1021\" alt=\"image\" src=\"https://github.com/user-attachments/assets/df911d7a-d3d0-44dc-b3c6-58607ff3807d\" /\u003e\n\n\n```json\n{\n  \"mcpServers\": {\n    \"smartdb\": {\n      \"name\": \"smartdb\",\n      \"type\": \"streamableHttp\",\n      \"description\": \"\",\n      \"isActive\": true,\n      \"url\": \"http://localhost:3000/mcp/\",\n      \"headers\": {\n        \"authorization\": \"bearer TOKEN值\"\n      }\n    }\n  }\n}\n```\n\n## 使用示例\n1. 查询default连接池的表数据\n    \u003cimg width=\"1136\" height=\"731\" alt=\"image\" src=\"https://github.com/user-attachments/assets/14e6adf6-f7a2-45a7-b4e6-df29cc9e2604\" /\u003e\n\n2. 查询其他连接池的表数据\n   \u003cimg width=\"1130\" height=\"805\" alt=\"image\" src=\"https://github.com/user-attachments/assets/e6419269-16c1-4a3b-aa73-d74647fe1bbd\" /\u003e\n\n3. 查询其他连接池、其他库的表数据\n   \u003cimg width=\"1127\" height=\"668\" alt=\"image\" src=\"https://github.com/user-attachments/assets/dd5cfea9-4d9b-46eb-b1cc-ad38963ed671\" /\u003e\n\n4. 修改表数据\n   \u003cimg width=\"1138\" height=\"696\" alt=\"image\" src=\"https://github.com/user-attachments/assets/930fb947-656f-41a7-93fa-2b83dd64b4ec\" /\u003e\n\n5. 数据库健康检测\n   \u003cimg width=\"1119\" height=\"3264\" alt=\"image\" src=\"https://github.com/user-attachments/assets/d065173b-140c-44f1-9ce8-16ac61562b38\" /\u003e\n\n6. sql优化\n   \u003cimg width=\"1570\" height=\"4107\" alt=\"image\" src=\"https://github.com/user-attachments/assets/594975e7-b040-4ccc-8e31-9423e6597ec2\" /\u003e\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwenb1n-dev%2FSmartDB_MCP","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwenb1n-dev%2FSmartDB_MCP","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwenb1n-dev%2FSmartDB_MCP/lists"}