db-metadata-extractor-mcp

mcp-name: io.github.Optisol-Business/db-metadata-extractor-mcp

数据库元数据提取器 MCP 服务

一个模型上下文协议（MCP）服务，可从 PostgreSQL、Snowflake、SQL Server、BigQuery 和 Oracle 数据库中提取并查询数据库架构元数据。

功能

• ✅ 多数据库支持：PostgreSQL、Snowflake、SQL Server（MSSQL）、BigQuery、Oracle
• ✅ 完整的架构提取：表、列、主键、索引、约束
• ✅ 本地 JSON 输出：将元数据直接保存到本地文件夹（无需云服务）
• ✅ 查询接口：按表名或列名搜索和筛选元数据
• ✅ 分页支持：高效浏览大型架构
• ✅ VS Code 集成：可与 VS Code Agent Mode 配合使用
• ✅ 可自定义 CLI：传输选项（stdio、HTTP）

安装

从 PyPI 安装

pip install db-metadata-extractor-mcp

从源代码安装

git clone https://github.com/Optisol-Business/db-metadata-extractor-mcp.git
cd db-metadata-extractor-mcp
pip install -e .

快速开始

1. 启动 MCP 服务

db-metadata-extractor-mcp

服务默认以 stdio 模式启动，并监听 MCP 客户端连接。

2. 在 Claude Desktop 中配置

将以下内容添加到 ~/.config/Claude/claude_desktop_config.json（macOS/Linux）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "db-metadata-extractor": {
      "command": "db-metadata-extractor-mcp",
      "args": [],
      "env": {}
    }
  }
}

重启 Claude Desktop。

3. 在 Claude 中使用

告诉 Claude：

从我的 PostgreSQL 数据库中提取元数据，并将其保存到 /tmp/output

Claude 将使用此服务的工具来提取并查询数据库架构。

工具

extract_metadata

从数据库中提取完整的架构元数据。

参数：

• db_type（必填）：postgresql、snowflake、sqlserver、bigquery、oracle
• output_path（必填）：用于保存 JSON 输出的本地目录
• database_name：数据库／架构名称
• host：数据库主机（BigQuery／Snowflake 无需此项）
• port：数据库端口
• username：数据库用户
• password：数据库密码
• schema_name：指定架构（可选）
• tables：要提取的表名数组（可选）
• account：Snowflake 账户 ID
• warehouse：Snowflake 仓库
• role_name：Snowflake 角色
• project_id：BigQuery 项目 ID
• service_account_key：BigQuery 服务账户 JSON（经过 base64 编码）

返回：

• 保存元数据的文件路径
• 汇总统计信息（表数量、列数量等）

query_metadata

查询先前提取的元数据。

参数：

• filepath（必填）：元数据 JSON 文件的路径
• table_name：按表名筛选（子字符串匹配）
• field_name：按列名筛选（子字符串匹配）
• page：页码（默认值：1）
• page_size：每页结果数（默认值：20）

返回：

• 与筛选条件匹配的分页表结果

示例

PostgreSQL

# Via Claude
"Extract all tables from my dev PostgreSQL database at localhost:5432"

Claude 将使用的参数：

{
  "db_type": "postgresql",
  "host": "localhost",
  "port": 5432,
  "database_name": "dev_db",
  "username": "postgres",
  "password": "your_password",
  "output_path": "/tmp/db_metadata"
}

Snowflake

"Extract schema from Snowflake account XYZ123"

参数：

{
  "db_type": "snowflake",
  "account": "XYZ123",
  "username": "your_user",
  "password": "your_password",
  "warehouse": "COMPUTE_WH",
  "role_name": "ANALYST",
  "database_name": "PRODUCTION",
  "output_path": "C:/metadata"
}

BigQuery

"Extract metadata from BigQuery project my-project-123"

参数：

{
  "db_type": "bigquery",
  "project_id": "my-project-123",
  "service_account_key": "base64_encoded_json_key",
  "output_path": "/tmp/bq_metadata"
}

高级用法

自定义传输方式

使用 HTTP 传输方式启动：

db-metadata-extractor-mcp --transport streamable-http --port 3000

环境变量

# Set database credentials via env
export DB_HOST=localhost
export DB_USER=postgres
export DB_PASSWORD=secret

db-metadata-extractor-mcp

输出格式

提取的元数据会保存为 JSON 文件，结构如下：

{
  "source": {
    "db_type": "postgresql",
    "extracted_at": "2026-04-09T14:30:00",
    "host": "localhost"
  },
  "schemas": [
    {
      "schema_name": "public",
      "tables": [
        {
          "table_name": "users",
          "columns": [
            {
              "column_name": "id",
              "data_type": "int",
              "is_nullable": false,
              "is_primary_key": true
            },
            {
              "column_name": "email",
              "data_type": "varchar",
              "is_nullable": false
            }
          ],
          "indexes": [
            {
              "index_name": "users_email_idx",
              "columns": ["email"]
            }
          ]
        }
      ]
    }
  ]
}

要求

• Python 3.8+
• PostgreSQL：psycopg2-binary
• Snowflake：snowflake-connector-python
• SQL Server：pyodbc、pymssql
• BigQuery：google-cloud-bigquery
• Oracle：oracledb

故障排除

连接错误

问题：“Unable to connect to database”

解决方案：验证凭据和网络访问：

# Test PostgreSQL connection
psql -h localhost -U postgres -c "SELECT 1"

# Test Snowflake
snowsql -a XYZ123 -u your_user

权限错误

问题：“Access denied”或“insufficient permissions”

解决方案：确保数据库用户拥有以下权限：

• 表上的 SELECT 权限
• 架构上的 USAGE 权限
• 数据库上的 CONNECT 权限

大型架构超时

问题：提取大型数据库时超时

解决方案：提取指定架构／表：

{
  "schema_name": "public",
  "tables": ["users", "orders"]  // Specify subset
}

许可证

MIT License — 参见 LICENSE 文件

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 提交 pull request

Support

• GitHub Issues: https://github.com/Optisol-Business/db-metadata-extractor-mcp/issues
• Documentation: See MCP_REGISTRY_GUIDE.md

Links

• PyPI: https://pypi.org/project/db-metadata-extractor-mcp/
• GitHub: https://github.com/Optisol-Business/db-metadata-extractor-mcp
• MCP Spec: https://modelcontextprotocol.io/