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 npmPython 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 헤더 없이 전송됩니다.
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 서버는 공유 비밀 + 이메일을 백엔드 브로커(POST /api/v1/mcp/exchange)의 범위 지정 JWT와 교환합니다.
토큰은 프로세스 메모리에 캐시됩니다.
jwt_token을 생략하는 모든 후속 HTTP 도구 호출은 세션 토큰을 자동으로 사용합니다.
에이전트는 auth_status로 세션을 검사하거나, auth_switch_user로 사용자를 전환하거나, auth_clear_session으로 세션을 지울 수 있습니다.
우선순위 | 소스 |
1 | 도구 호출 시 전달된 |
2 |
|
3 |
|
변수 | 목적 |
| 백엔드 브로커 엔드포인트의 전체 URL |
|
|
| N초 미만으로 남았을 때 새로 고침 (기본값: 60) |
도구 | 설명 |
| 주어진 이메일에 대한 세션 토큰 획득 |
| 활성 세션을 다른 사용자로 전환 (시작과 동일) |
| 현재 세션 검사 (이메일, 만료, 새로 고침 필요 여부) |
| 메모리에서 캐시된 세션 토큰 삭제 |
전체 에이전트 참조는 **docs/SESSION_AUTH.md**를 참조하세요.
가상 환경을 활성화하고 종속성을 설치한 후, 다음 명령 중 하나로 MCP 서버를 시작하세요:
workbench-mcppython -m workbench_mcp.server로컬 MCP 개발 및 디버깅을 위해 MCP Inspector는 빠른 수동 테스트 루프를 제공합니다:
npx @modelcontextprotocol/inspector .venv/bin/python -m workbench_mcp.serverInspector에서 중단점 디버깅을 위해 debugpy 하에서 MCP 서버를 실행하려면:
npx @modelcontextprotocol/inspector .venv/bin/python -m debugpy --listen 127.0.0.1:5678 -m workbench_mcp.server실행 후 Inspector UI를 열고 STDIO를 통해 연결한 다음 health, describe_object, exec_proc_preview와 같은 도구를 테스트하세요.
중단점 (debugpy): 디버거에는 포트 5678을 사용하세요 (6274는 Inspector 웹 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 서버가 이미 구성되어 있다면 전체 파일을 바꾸지 말고 기존 servers 객체 안에 workbench-mcp를 추가하세요.
.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가 구성된 후 일반적인 검증 흐름은 다음과 같습니다:
검사할 함수, 프로시저, 테이블 또는 뷰를 설명(describe)합니다.
해당 객체를 이해하는 데 필요한 지원 구성 또는 참조 데이터를 미리 봅니다.
알려진 입력값으로 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.