内容
# MCP 服务器通过 SQLAlchemy 的 ODBC 连接
一个使用 **FastAPI**、**pyodbc** 和 **SQLAlchemy** 构建的轻量级 MCP（模型上下文协议）服务器。该服务器与 Virtuoso 数据库管理系统和其他实现 SQLAlchemy 提供程序的数据库后端兼容。
## 功能特点
- **获取模式**: 从连接的数据库中获取并列出所有模式名称。
- **获取表**: 检索特定模式或所有模式的表信息。
- **描述表**: 生成表的详细描述，包括：
- 列名和数据类型
- 可空属性
- 主键和外键
- **搜索表**: 根据名称子字符串筛选和检索表。
- **执行存储过程**: 在 Virtuoso 的情况下，执行存储过程并获取结果。
- **执行查询**:
- JSONL 结果格式：针对结构化响应进行了优化。
- Markdown 表格格式：适用于报告和可视化。
## 前置条件
1. **安装 uv**：
```bash
pip install uv
```
或使用 Homebrew：
```bash
brew install uv
```
2. **unixODBC 运行时环境检查**:
1. 通过运行以下命令检查安装配置（即关键 INI 文件的位置）：`odbcinst -j`
2. 通过运行以下命令列出可用的数据源名称：`odbcinst -q -s`
3. **ODBC DSN 设置**: 为目标数据库配置 ODBC 数据源名称（`~/.odbc.ini`）。Virtuoso 数据库管理系统的示例：
```
[VOS]
Description = OpenLink Virtuoso
Driver = /path/to/virtodbcu_r.so
Database = Demo
Address = localhost:1111
WideAsUTF16 = Yes
```
3. **SQLAlchemy URL 绑定**: 使用以下格式：
```
virtuoso+pyodbc://user:password@VOS
```
## 安装
克隆此仓库：
```bash
git clone https://github.com/OpenLinkSoftware/mcp-sqlalchemy-server.git
cd mcp-sqlalchemy-server
```
## 环境变量
更新您的 `.env` 文件，覆盖默认值以匹配您的偏好：
```
ODBC_DSN=VOS
ODBC_USER=dba
ODBC_PASSWORD=dba
API_KEY=xxx
```
---
## 配置
对于 **Claude Desktop** 用户：
在 `claude_desktop_config.json` 中添加以下内容：
```json
{
"mcpServers": {
"my_database": {
"command": "uv",
"args": ["--directory", "/path/to/mcp-sqlalchemy-server", "run", "mcp-sqlalchemy-server"],
"env": {
"ODBC_DSN": "dsn_name",
"ODBC_USER": "username",
"ODBC_PASSWORD": "password",
"API_KEY": "sk-xxx"
}
}
}
}
```
---
# 使用
## 数据库管理系统（DBMS）连接 URL
以下是使用此 mcp-server 测试过的 DBMS 系统的 pyodbc URL 示例。
| 数据库 | URL 格式 |
|---------------|-----------------------------------------------|
| Virtuoso DBMS | `virtuoso+pyodbc://user:password@ODBC_DSN` |
| PostgreSQL | `postgresql://user:password@localhost/dbname` |
| MySQL | `mysql+pymysql://user:password@localhost/dbname` |
| SQLite | `sqlite:///path/to/database.db` |
连接后，您可以通过 Claude 与 WhatsApp 联系人互动，利用 Claude 的 AI 功能在 WhatsApp 会话中。
## 提供的工具
### 概述
| 名称 | 描述 |
|---|---|
| podbc_get_schemas | 列出连接到数据库管理系统的数据库模式。 |
| podbc_get_tables | 列出与选定数据库模式关联的表。 |
| podbc_describe_table | 提供与指定数据库模式关联的表的描述，包括列名、数据类型、空值处理、自增、主键和外键信息。 |
| podbc_filter_table_names | 根据 `q` 输入字段中的子字符串模式列出表。 |
| podbc_query_database | 执行 SQL 查询并以 JSONL 格式返回结果。 |
| podbc_execute_query | 执行 SQL 查询并以 JSONL 格式返回结果。 |
| podbc_execute_query_md | 执行 SQL 查询并以 Markdown 表格格式返回结果。 |
| podbc_spasql_query | 执行 SPASQL 查询并返回结果。 |
| podbc_sparql_query | 执行 SPARQL 查询并返回结果。 |
| podbc_virtuoso_support_ai | 与 Virtuoso 支持助手/代理交互 - Virtuoso 特有的与 LLM 交互的功能。 |
### 详细描述
- **podbc_get_schemas**
- 检索并返回连接数据库的所有模式名称列表。
- 输入参数：
- `user`（字符串，可选）：数据库用户名。默认为“demo”。
- `password`（字符串，可选）：数据库密码。默认为“demo”。
- `dsn`（字符串，可选）：ODBC 数据源名称。默认为“Local Virtuoso”。
- 返回模式名称的 JSON 字符串数组。
- **podbc_get_tables**
- 检索并返回指定模式中表的列表。如果未提供模式，则使用连接的默认模式。
- 输入参数：
- `schema`（字符串，可选）：用于筛选表的数据库模式。默认为连接默认模式。
- `user`（字符串，可选）：数据库用户名。默认为“demo”。
- `password`（字符串，可选）：数据库密码。默认为“demo”。
- `dsn`（字符串，可选）：ODBC 数据源名称。默认为“Local Virtuoso”。
- 返回包含表信息（例如 TABLE_CAT、TABLE_SCHEM、TABLE_NAME、TABLE_TYPE）的 JSON 字符串。
- **podbc_filter_table_names**
- 筛选并返回表名中包含特定子字符串的表信息。
- 输入参数：
- `q`（字符串，必填）：要在表名中搜索的子字符串。
- `schema`（字符串，可选）：用于筛选表的数据库模式。默认为连接默认模式。
- `user`（字符串，可选）：数据库用户名。默认为“demo”。
- `password`（字符串，可选）：数据库密码。默认为“demo”。
- `dsn`（字符串，可选）：ODBC 数据源名称。默认为“Local Virtuoso”。
- 返回匹配表的 JSON 字符串。
- **podbc_describe_table**
- 检索并返回特定表的列的详细信息。
- 输入参数：
- `schema`（字符串，必填）：包含表的数据库模式名称。
- `table`（字符串，必填）：要描述的表名。
- `user`（字符串，可选）：数据库用户名。默认为“demo”。
- `password`（字符串，可选）：数据库密码。默认为“demo”。
- `dsn`（字符串，可选）：ODBC 数据源名称。默认为“Local Virtuoso”。
- 返回描述表列的 JSON 字符串（例如 COLUMN_NAME、TYPE_NAME、COLUMN_SIZE、IS_NULLABLE）。
- **podbc_query_database**
- 执行标准 SQL 查询并以 JSON 格式返回结果。
- 输入参数：
- `query`（字符串，必填）：要执行的 SQL 查询字符串。
- `user`（字符串，可选）：数据库用户名。默认为“demo”。
- `password`（字符串，可选）：数据库密码。默认为“demo”。
- `dsn`（字符串，可选）：ODBC 数据源名称。默认为“Local Virtuoso”。
- 返回查询结果为 JSON 字符串。
- **podbc_query_database_md**
- 执行标准 SQL 查询并以 Markdown 表格格式返回结果。
- 输入参数：
- `query`（字符串，必填）：要执行的 SQL 查询字符串。
- `user`（字符串，可选）：数据库用户名。默认为“demo”。
- `password`（字符串，可选）：数据库密码。默认为“demo”。
- `dsn`（字符串，可选）：ODBC 数据源名称。默认为“Local Virtuoso”。
- 返回查询结果为 Markdown 表格字符串。
- **podbc_query_database_jsonl**
- 执行标准 SQL 查询并以 JSON Lines（JSONL）格式返回结果（每行一个 JSON 对象）。
- 输入参数：
- `query`（字符串，必填）：要执行的 SQL 查询字符串。
- `user`（字符串，可选）：数据库用户名。默认为“demo”。
- `password`（字符串，可选）：数据库密码。默认为“demo”。
- `dsn`（字符串，可选）：ODBC 数据源名称。默认为“Local Virtuoso”。
- 返回查询结果为 JSONL 字符串。
- **podbc_spasql_query**
- 执行 SPASQL（SQL/SPARQL 混合）查询并返回结果。这是 Virtuoso 特有的功能。
- 输入参数：
- `query`（字符串，必填）：SPASQL 查询字符串。
- `max_rows`（数字，可选）：要返回的最大行数。默认为 20。
- `timeout`（数字，可选）：查询超时，毫秒。默认为 30000。
- `user`（字符串，可选）：数据库用户名。默认为“demo”。
- `password`（字符串，可选）：数据库密码。默认为“demo”。
- `dsn`（字符串，可选）：ODBC 数据源名称。默认为“Local Virtuoso”。
- 返回底层存储过程调用的结果（例如 `Demo.demo.execute_spasql_query`）。
- **podbc_sparql_query**
- 执行 SPARQL 查询并返回结果。这是 Virtuoso 特有的功能。
- 输入参数：
- `query`（字符串，必填）：SPARQL 查询字符串。
- `format`（字符串，可选）：所需结果格式。默认为 'json'。
- `timeout`（数字，可选）：查询超时，毫秒。默认为 30000。
- `user`（字符串，可选）：数据库用户名。默认为“demo”。
- `password`（字符串，可选）：数据库密码。默认为“demo”。
- `dsn`（字符串，可选）：ODBC 数据源名称。默认为“Local Virtuoso”。
- 返回底层函数调用的结果（例如 `"UB".dba."sparqlQuery"`）。
- **podbc_virtuoso_support_ai**
- 利用 Virtuoso 特有的 AI 助手函数，传递提示和可选的 API 密钥。这是 Virtuoso 特有的功能。
- 输入参数：
- `prompt`（字符串，必填）：AI 函数的提示文本。
- `api_key`（字符串，可选）：AI 服务的 API 密钥。默认为“none”。
- `user`（字符串，可选）：数据库用户名。默认为“demo”。
- `password`（字符串，可选）：数据库密码。默认为“demo”。
- `dsn`（字符串，可选）：ODBC 数据源名称。默认为“Local Virtuoso”。
- 返回 AI 支持助手函数调用的结果（例如 `DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI`）。
## 故障排除
为了更容易的故障排除：
1. 安装 MCP 检视器：
```bash
npm install -g @modelcontextprotocol/inspector
```
2. 启动检视器：
```bash
npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-sqlalchemy-server run mcp-sqlalchemy-server
```
访问提供的 URL 以排查服务器交互问题。
连接信息
猜你喜欢
暂无推荐服务器