一个用于 Fedora/Linux 系统上交互式 PostgreSQL 数据探索、API 集成和自动化的本地 Python MCP 服务器。
版本 1 包括：
针对 Fedora/Linux 系统的 Python 虚拟环境设置
通过 .env 文件配置的 PostgreSQL 18 连接
MCP 工具，用于：
发现表、列和模式结构
运行只读查询预览
执行带有临时表支持的受限 SQL 批处理
调用 PostgreSQL 存储函数和过程
通过完整 URL 请求访问外部 API
执行 PATH 中可用的 bash 脚本
强制安全：禁止持久化模式和数据修改
支持 SQL 批处理内的会话级临时表工作流
Related MCP server: PostgreSQL MCP Server
首先安装所需的系统包：
sudo dnf install -y python3 python3-pip nodejs npm需要 Python 3.12 或更高版本。如果管理多个版本，请使用 pyenv 或类似工具。
在项目根目录下，创建并激活 Python 虚拟环境：
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .复制示例配置并填充 PostgreSQL 连接详细信息：
cp .env.example .env必需：
DB_HOST — PostgreSQL 服务器主机名
DB_NAME — 数据库名称
DB_USER — 数据库用户名
DB_PASSWORD — 数据库密码
可选（调优）：
DB_PORT — 连接端口（默认：5432）
DB_SSLMODE — SSL 模式（默认：prefer）
DB_APPLICATION_NAME — 应用程序标识符
DB_QUERY_TIMEOUT_SECONDS — 查询超时（默认：30）
DB_MAX_ROWS — 每个结果集的最大行数（默认：100）
DB_MAX_RESULT_SETS — 每个批次的最大结果集数（默认：5）
DB_OBJECT_PREVIEW_CHARS — 最大定义预览长度（默认：4000）
本地开发示例：
DB_HOST=localhost
DB_PORT=5432
DB_NAME=app_dev
DB_USER=app_user
DB_PASSWORD=your-secure-password
DB_SSLMODE=preferHTTP 工具每次调用使用完整 URL，不需要 API 配置文件。
支持的环境设置：
变量 | 用途 |
| HTTP 请求超时 |
| HTTP 工具返回的最大响应字节数 |
|
|
| 当工具调用未传递 |
| 作为 |
调用形状示例：
url: https://localhost:44331/api/breakouts/filter/1871161/dd-table?ParameterSetId=231022
method: GET对于经过身份验证的调用，请在 .env（或进程环境变量）中设置 API_BEARER_TOKEN。除非调用者传递了自己的 jwt_token，否则 HTTP 工具会自动使用它。
HTTP 工具支持两种授权来源：
在工具调用中传递的 jwt_token
来自 .env 或进程环境的 API_BEARER_TOKEN
如果提供了 jwt_token，该令牌将作为 Authorization: Bearer <jwt_token> 转发。
如果 jwt_token 被省略或为空，服务器将回退到 API_BEARER_TOKEN。
如果两个值都不存在，请求将不带 Authorization 标头发送。
不要将 bearer token 放在 headers.Authorization 中。
MCP 服务器会从 headers 中剥离 Authorization，并且仅接受通过专用 jwt_token 字段进行的身份验证。
这可以防止意外的标头冲突，并使令牌优先级明确。
{
"url": "https://localhost:5001/api/v1/sales/my-sales"
}{
"url": "https://localhost:5001/api/v1/sales/my-sales",
"jwt_token": "eyJhbGciOi..."
}{
"url": "https://localhost:5001/api/v1/sales/my-sales",
"jwt_token": "eyJhbGciOi...",
"headers": {
"Accept": "application/json"
}
}相同的 jwt_token 字段在 http_get、http_head、http_post、http_put、http_patch 和 http_delete 上可用。
代理无需为每次调用传递 jwt_token，而是可以获取一次会话级 JWT，并让每个 HTTP 工具调用在会话的其余部分自动使用它。
代理使用目标用户的电子邮件调用 auth_start_session。
MCP 服务器将共享密钥 + 电子邮件交换为来自后端代理的范围限定 JWT (POST /api/v1/mcp/exchange)。
令牌缓存在进程内存中。
随后每个省略 jwt_token 的 HTTP 工具调用都会自动使用会话令牌。
代理可以使用 auth_status 检查会话，使用 auth_switch_user 切换用户，或使用 auth_clear_session 清除它。
优先级 | 来源 |
1 | 工具调用中传递的 |
2 |
|
3 |
|
变量 | 用途 |
| 后端代理端点的完整 URL |
| 在 |
| 当剩余时间少于 N 秒时刷新（默认：60） |
工具 | 描述 |
| 获取给定电子邮件的会话令牌 |
| 将活动会话切换到其他用户（与 start 相同） |
| 检查当前会话（电子邮件、过期时间、是否需要刷新） |
| 从内存中清除缓存的会话令牌 |
请参阅 docs/SESSION_AUTH.md 获取完整的代理参考。
激活虚拟环境并安装依赖项后，使用以下任一命令启动 MCP 服务器：
workbench-mcppython -m workbench_mcp.server对于本地 MCP 开发和调试，MCP 检查器提供了快速的手动测试循环：
npx @modelcontextprotocol/inspector .venv/bin/python -m workbench_mcp.server要在 debugpy 下启动 MCP 服务器以在检查器中进行断点调试：
npx @modelcontextprotocol/inspector .venv/bin/python -m debugpy --listen 127.0.0.1:5678 -m workbench_mcp.server启动后，打开检查器 UI，通过 STDIO 连接，并测试诸如 health、describe_object 和 exec_proc_preview 等工具。
断点 (debugpy)： 使用端口 5678 进行调试，而不是 6274（6274 仅是检查器 Web UI）。分步工作流和“之前出了什么问题”在 docs/DEBUG_MCP.md 中。
要在 VS Code 中注册本地 MCP 服务器，请在工作区 MCP 配置文件中添加一个条目：
工作区文件：.vscode/mcp.json
配置示例：
{
"servers": {
"workbench-mcp": {
"type": "stdio",
"command": "/absolute/path/to/workbench-mcp/.venv/bin/python",
"args": ["-m", "workbench_mcp.server"]
}
}
}将命令路径替换为虚拟环境 Python 的本地存储库路径。
您可以在以下任一位置提供环境变量值：
workbench-mcp/.env
.vscode/mcp.json 中的 env — VS Code 将这些注入到 MCP 服务器进程中。
优先级： 进程环境（包括 .vscode/mcp.json -> env）会覆盖 .env 中相同键的值。
VS Code 中 HTTP 调优示例：
{
"servers": {
"workbench-mcp": {
"type": "stdio",
"command": "/absolute/path/to/workbench-mcp/.venv/bin/python",
"args": ["-m", "workbench_mcp.server"],
"env": {
"API_TIMEOUT_SECONDS": "30",
"API_MAX_RESPONSE_BYTES": "2097152",
"API_VERIFY_SSL": "false"
}
}
}
}不要提交真实的令牌。建议使用仅限本地的工作区配置，或者省略 env 并使用 .env（应将其排除在 git 之外）。
如果已经配置了其他 MCP 服务器，请将 workbench-mcp 添加到现有的 servers 对象中，而不是替换整个文件。
保存 .vscode/mcp.json 后，重新加载 VS Code 或刷新 MCP 服务器，以便发现新服务器。服务器加载后，在测试数据库过程之前运行 health 工具。
health
describe_object
list_tables_and_columns
preview_query
execute_readonly_sql
exec_proc_preview
exec_function_preview
insert_row
insert_rows
http_get
http_head
http_post
http_put
http_patch
http_delete
auth_start_session
auth_switch_user
auth_status
auth_clear_session
execute_path_bash_script (脚本名称通过 PATH 解析)
在临时 PostgreSQL 批处理中禁止持久化 DDL 和 DML
仅允许临时表写入，且仅限于在当前批处理中创建的临时表
preview_query 仅允许 SELECT 语句和基于 CTE 的读取
exec_proc_preview 可以执行 PostgreSQL 过程和函数；重载例程应使用签名传递，例如 public.my_func(integer, text)
execute_path_bash_script 仅接受脚本名称（而非路径），通过 PATH 解析它们，并通过 bash 执行
配置 .env 后，典型的验证流程是：
描述要检查的函数、过程、表或视图。
预览理解该对象所需的辅助配置或参考数据。
使用已知输入运行 exec_proc_preview、preview_query 或 execute_readonly_sql。
将返回的形状与正在评估的功能、调查或调试场景进行比较。
对于位置 PostgreSQL 函数调用，请使用 exec_function_preview。
将 PostgreSQL 数组作为普通 JSON 列表传递。
SQL 目标示例：
select * from sales."Fn_GetSalesChamps"(2, 2025, array[1,2,5,6,7,8,9,10,11,12,15,16,18,19], 5);等效的 MCP 工具输入：
{
"function_name": "sales.\"Fn_GetSalesChamps\"",
"parameters": [2, 2025, [1, 2, 5, 6, 7, 8, 9, 10, 11, 12, 15, 16, 18, 19], 5]
}单行插入：
{
"table_name": "sales.orders",
"row": {
"customer_id": 10,
"status": "new"
},
"returning_columns": ["order_id"]
}批量插入：
{
"table_name": "sales.orders",
"rows": [
{"customer_id": 10, "status": "new"},
{"customer_id": 11, "status": "pending"}
]
}Clear the active session token from memory.
After this call HTTP tools will fall back to API_BEARER_TOKEN (if
configured) or make unauthenticated requests.
dict
{"ok": True, "message": "Session cleared."}.
Inputs: no named parameters. Returns: object
Acquire a session-scoped JWT for email from the backend broker.
After a successful call every HTTP tool call in this session will
automatically use the returned token (unless the tool call provides
its own jwt_token).
email: The user whose identity the MCP session will impersonate. reason: Optional free-text description of why this session is needed. Stored in the JWT claims for audit purposes.
dict
ok=True with email, display_name, user_name,
store on success; ok=False with error on failure.
Inputs: email (required), reason. Returns: object
Return the current session status without exposing the raw token.
dict
active=False when no session is set; otherwise active=True
with email, display_name, expires_in_seconds, and
needs_refresh.
Inputs: no named parameters. Returns: object
Switch the active session to a different user.
Equivalent to calling auth_start_session — provided as a semantic
alias when the intent is to change the active user rather than start a
fresh session.
email: The new user to impersonate. reason: Optional free-text description of why the switch is needed.
dict
Same shape as auth_start_session.
Inputs: email (required), reason. Returns: object
Retrieve structural details, parameters, and definition for a database object.
Inputs: object_name (required). Returns: object
Execute a PostgreSQL function with positional parameters and return preview rows.
Use this tool for function calls such as
sales."Fn_GetSalesChamps"(2, 2025, ARRAY[1,2,5], 5).
Pass arguments in positional order using JSON-compatible values:
scalars: 2, 2025, 5
arrays: [1, 2, 5]
null: null
PostgreSQL array parameters should be passed as normal lists; psycopg adapts them to PostgreSQL arrays automatically.
Inputs: function_name (required), parameters, max_rows. Returns: object
Execute PostgreSQL functions or procedures with optional parameters and result limiting.
Inputs: proc_name (required), parameters, max_rows. Returns: object
Execute read-only SQL batches with support for temporary tables within the session.
Inputs: sql (required), max_rows. Returns: object
Provide system status and configuration details without exposing secrets.
Inputs: no named parameters. Returns: object
Send an HTTP DELETE request.
Use for delete operations. Some APIs allow delete payloads; if needed,
provide body as JSON object/array or UTF-8 text.
Pass jwt_token to forward the caller's JWT for this request only.
Inputs: url (required), body, content_type, headers, +1 more. Returns: object
Send an HTTP GET request.
Use for read-only resource retrieval. Provide a full URL.
Pass jwt_token to forward the caller's JWT for this request only.
If jwt_token is omitted, API_BEARER_TOKEN is used when configured.
headers.Authorization is ignored; use jwt_token instead.
Inputs: url (required), headers, jwt_token. Returns: object
Send an HTTP HEAD request.
Use for metadata/status checks without retrieving a full body.
Pass jwt_token to override the default environment token for this call.
headers.Authorization is ignored; use jwt_token instead.
Inputs: url (required), headers, jwt_token. Returns: object
Send an HTTP PATCH request.
Use for partial updates.
body accepts JSON object/array or UTF-8 text.
Pass jwt_token to forward the caller's JWT for this request only.
Inputs: url (required), body, content_type, headers, +1 more. Returns: object
Send an HTTP POST request.
Use for create/actions. Provide a full URL.
body accepts JSON object/array or UTF-8 text.
content_type optionally overrides the Content-Type header.
Pass jwt_token to forward the caller's JWT for this request only.
Inputs: url (required), body, content_type, headers, +1 more. Returns: object
Send an HTTP PUT request.
Use for full updates/replacements.
body accepts JSON object/array or UTF-8 text.
Pass jwt_token to forward the caller's JWT for this request only.
Inputs: url (required), body, content_type, headers, +1 more. Returns: object
Insert a single row into a PostgreSQL table.
Use this tool when you need one explicit insert with structured values.
table_name: table target, optionally schema-qualified
row: object mapping column names to values
returning_columns: optional list of columns to return via RETURNING
Example:
table_name: sales.orders
row: { "customer_id": 10, "status": "new" }
returning_columns: ["order_id"]
Inputs: table_name (required), row (required), returning_columns. Returns: object
Insert multiple rows into a PostgreSQL table in one batch.
Use this tool for bulk inserts where every row has the same columns.
table_name: table target, optionally schema-qualified
rows: list of objects mapping column names to values
returning_columns: optional list of columns to return from inserted rows
Notes:
Every row must use the same columns in the same order.
Arrays can be passed as JSON lists and psycopg adapts them automatically.
Inputs: table_name (required), rows (required), returning_columns. Returns: object
Discover tables and columns with optional filtering by schema or keyword search.
Inputs: schema_name, search_term, limit. Returns: object
Execute read-only SELECT statements and CTEs with safety validation and row limits.
Inputs: sql (required), max_rows. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 19 tools
Most tools have distinct purposes, but there is some overlap between exec_function_preview and exec_proc_preview, which both execute PostgreSQL functions/procedures with similar parameters. The HTTP tools (http_get, http_post, etc.) are clearly differentiated by HTTP method, and auth tools are well-separated. Overall, the descriptions help clarify boundaries, but the function/procedure execution tools could cause confusion.
Tool names follow a highly consistent snake_case pattern with clear verb_noun structures. Auth tools use auth_ prefix (e.g., auth_clear_session), HTTP tools use http_ prefix (e.g., http_get), and database tools use descriptive verbs like describe_, exec_, insert_, list_, preview_. There are no deviations in naming style across the set.
With 19 tools, the count is slightly high but reasonable for a workbench server that combines authentication, HTTP operations, and database interactions. It covers multiple domains comprehensively without being excessive. A few tools might be consolidated (e.g., the two function execution tools), but overall the scope justifies the number.
The toolset provides complete coverage for its intended domains: authentication (session management), HTTP operations (full CRUD via different methods), and PostgreSQL database interactions (querying, inserting, describing objects, executing functions). There are no obvious gaps; agents can perform end-to-end workflows involving data retrieval, manipulation, and API calls with proper auth handling.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Hosted PostgreSQL MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.