환경설정

MCP 서버

TablePlus 에 내장된 MCP(Model Context Protocol) 서버를 사용하면 Claude Code, Codex 또는 기타 MCP 클라이언트와 같은 AI 도구가 저장된 연결을 목록으로 표시하고, 이를 열어 쿼리를 실행할 수 있습니다. LLM Plugin 의 커스텀 에이전트도 동일한 서버를 통해 데이터베이스에 접근합니다.

TablePlus에서 Mac에서 실행되는 서버입니다. 클라이언들은 접근 토큰을 통해 연결되며, 사용자는 각 토큰이 어떤 작업을 수행할 수 있는지, 어떤 연결을 볼 수 있는지 결정합니다.

서버를 켭니다

  1. 설정 > MCP
  2. Enable MCP Server를 확인하세요.

상태 표시줄에는 MCP 서버가 포트: 51003(또는 선택한 포트)에서 실행 중이며 연결된 클라이언트 수가 표시됩니다. 활성화되면 TablePlus 를 열 때마다 서버가 자동으로 시작됩니다.

항목 검색 및 열기에서 이 패널을 열 수도 있습니다: ⌘ + P를 누르고 MCP Server를 선택합니다.

설정의 MCP 패널에서 서버가 실행 중일 때, 보안 옵션 및 클라이언트 설정 버튼
설정 > MCP

서버 옵션

옵션 설명
Preferred Port 서버가 경청하는 포트입니다. 기본값은 51003이며, 32000 에서 61000 사이의 포트를 사용하세요.
Allow remote access (TLS) 다른 기기가 HTTPS 를 통해 연결되도록 합니다. 기본적으로 서버는 사용자의 Mac 에서만 연결을 허용합니다.
Export Certificate… 서버의 자체 서명된 TLS 인증서(tableplus-mcp.pem)를 내보냅니다. 원격 기기에서 이를 설치하여 서버를 신뢰하도록 합니다. 원격 접속이 활성화된 경우에만 사용 가능합니다.
위험한 쿼리에 대한 승인 필요 Silent 모드 연결 시, 데이터 또는 구조를 변경하는 쿼리를 실행하기 전에 사용자에게 확인을 요청합니다. 기본값으로 활성화됩니다. 자세한 내용은 쿼리 승인을 참조하세요.
Auto-generate Access Token for tableplus-mcp tableplus-mcp 명령은 직접 생성한 토큰 없이 연결할 수 있습니다. 기본값으로 활성화됩니다.

포트 변경, 원격 접속, 또는 자동 생성 옵션을 변경하면 서버가 재시작됩니다.

고객 설정

고객 설정에서 Add to Claude Code, Add to Codex, Add to Grok Build 또는 Add to Antigravity를 클릭하여 Mac 에 설치된 코딩 에이전트에 TablePlus 를 추가한 후 에이전트를 재시작합니다. Others…를 클릭하여 Cursor, VS Code (GitHub Copilot), Cline, Kilo Code, OpenCode, Devin Desktop, Kiro, GitHub Copilot CLI, Factory Droid 및 Augment Code 에 추가합니다. 에이전트가 TablePlus 를 포함하면 버튼이 Remove from …으로 변경됩니다. 에이전트가 이전 위치에서 TablePlus 를 실행 중이 경우, 예를 들어 앱을 이동한 후 버튼은 Update in …으로 표시됩니다.

기타 클라이언트를 수동으로 설정하려면 Manual Setup…을 클릭하고 다음을 선택하세요.

  • 설명서: tableplus-mcp 명령에 대한 경로로, 로컬 (stdio) MCP 서버를 시작하는 모든 클라이언트에 적용됩니다.
  • HTTP Server: 스트림 가능한 HTTP 를 통해 연결하는 클라이언트의 엔드포인트 (예: http://127.0.0.1:51003/mcp) 입니다. 이러한 클라이언트는 Authorization: Bearer <token> 헤더에 접근 토큰을 보냅니다.

tableplus-mcp는 TablePlus 앱 패키지에 포함된 작은 명령어입니다 (TablePlus.app/Contents/MacOS/tableplus-mcp). 이 명령어는 클라이언트의 요청을 실행 중인 서버로 전달합니다. TablePlus가 실행되지 않을 경우, 먼저 TablePlus를 백그라운드에서 실행합니다. MCP 서버를 활성화해야 합니다.

Auto-generate Access Token for tableplus-mcp를 끄면 에이전트를 한 번에 추가할 수 없습니다. 대신 Manual Setup…를 사용하세요: Manual 명령에는 TABLEPLUS_MCP_ACCESS_TOKEN 변수가 포함되어 있습니다. YOUR_ACCESS_TOKEN로 생성한 토큰을 대입하세요.

액세스 토큰

모든 고객은 접근 토큰이 필요합니다. 이 토큰은 고객이 무엇을 할 수 있는지를 결정합니다.

권한 클라이언트가 할 수 있는 작업
Read Only 연결을 열거나 읽기 전용 쿼리(예: SELECT)를 실행할 수 있습니다. 다른 쿼리는 거부됩니다.
Read & Write Read Only 모드 내의 모든 기능, 데이터나 구조를 변경하는 쿼리까지 실행 가능.
전체 접근 권한 모든 권한입니다.
(각 연결당) 각 연결마다 선택된 Read Only 또는 Read & Write

토큰 생성

  1. Settings > MCP 에서 토큰 목록 아래의 Add 버튼을 클릭합니다.
  2. 다음으로 Token Name을 입력하세요. 예를 들어, 클라이언트 또는 머신의 이름과 같이 사용합니다.
  3. Permissions을 선택합니다.
  4. 접근 권한에서 Allow All를 선택하여 저장된 모든 연결에 접근하거나, Limited를 선택하고 토큰이 사용할 수 있는 연결 (또는 연결 그룹) 을 확인하세요.
  5. Generate Token을 클릭합니다.

즉시 토큰을 복사하세요. TablePlus는 이 값을 한 번만 보여줍니다.

Custom (per connection) 옵션을 선택하면 목록에 있는 각 연결마다 Read Only 또는 Read & Write를 선택할 수 있는 팝업이 표시됩니다. 연결은 기본적으로 Read & Write 권한으로 시작하며, Allow All 옵션을 선택하면 나중에 추가된 연결도 Read & Write 권한을 갖게 됩니다. Read Only 연결에서 데이터를 변경하는 쿼리를 실행하면 TablePlus 가 이를 거부합니다. 토큰 목록은 이러한 토큰의 권한을 Custom으로 표시합니다.

“Acme 스토어에 제한된 접근 권한과 읽기 전용으로 ‘Create MCP 토큰’ 창이 표시됩니다.”
액세스 토큰 생성

토큰 관리

토큰 목록은 각 토큰의 이름, 접두사 (토큰의 처음 문자), 권한, 상태, 생성 날짜 및 마지막 사용 날짜를 표시합니다.

  • 토큰을 더블 클릭하여 상세 정보를 확인하세요.
  • 취소는 토큰을 비활성화합니다. 해당 토큰을 사용하는 클라이언트는 연결이 끊어지지만, 토큰은 Revoked로 목록에 남아 있습니다.
  • Delete은 목록에서 토큰을 제거합니다. 해당 토큰을 사용하는 클라이언트는 연결이 끊깁니다.

토큰은 macOS 키체인에 저장됩니다. TablePlus 가 tableplus-mcp 에 대해 자동으로 생성한 토큰은 목록에 표시되지 않습니다.

고객이 할 수 있는 것

고객들은 다음 도구를 제공받습니다.

도구 설명
list_connections 토큰이 접근할 수 있는 저장된 연결을 나열합니다.
list_open_connections TablePlus 에서 현재 열려 있는 연결을 나열합니다.
open_connection 저장된 연결을 새 탭이나 새 창에서 엽니다.
disconnect 연결을 종료하거나 해당 데이터베이스 중 하나를 종료합니다.
execute_read_query 읽기 전용 쿼리 또는 스크립트를 실행합니다.
execute_query 임의의 문장 또는 스크립트를 실행합니다. Read & Write 또는 Full Access 권한이 필요합니다.
list_tables 연결의 현재 데이터베이스에 있는 테이블과 뷰를 나열하고, 각각의 스키마와 유형을 표시합니다.
describe_table 테이블 또는 뷰가 어떻게 생성되는지 보여줍니다: CREATE 문, 열, 데이터 타입, 키 및 인덱스를 포함합니다.

이 도구들은 클라이언트가 메트릭 보드를 조회하고 생성할 수 있습니다.

도구 설명
metrics_board_list 연결의 지표 보드 목록을 표시하고, 현재 화면에 표시된 보드도 함께 표시합니다.
metrics_board_get 판의 설정과 항목, 그리고 그 위치를 확인합니다.
metrics_board_log 회의 항목의 실행 내역, 오류, 행 수 및 쿼리 정보를 확인하세요.
metrics_board_connections 연결 항목이 사용할 수 있는 저장된 연결 목록을 표시합니다.
metrics_board_create 빈 보드를 추가하고 표시합니다. Read & Write 또는 전체 접근 권한이 필요합니다.
metrics_board_apply 보드의 항목을 추가, 변경, 연결 및 제거하고 설정을 변경할 수 있습니다. Read & Write 또는 Full Access 권한이 필요합니다.
metrics_board_arrange 화살표 사이의 물건들 사이에 판을 놓습니다. Read & Write 또는 전체 접근 권한가 필요합니다.
metrics_board_run 아이템을 사용하는 방법으로, 예를 들어 버튼을 누르거나 입력 필드를 제출하는 것과 같습니다. Read & Write 또는 전체 접근 권한가 필요합니다.

데이터를 변경하는 항목 쿼리는 실행되기 전에 귀하의 승인을 기다립니다.

쿼리는 최대 300초 동안 실행될 수 있습니다. 쿼리는 연결의 작업 영역에서 실행되므로, 콘솔 로그(console log)에 표시됩니다.

고객들은 또한 저장된 쿼리, 각 연결의 쿼리 기록, 그리고 분석 대시보드를 확인할 수 있습니다. 하지만 라이선스 소유자가 해당 기능을 비활성화했을 경우 쿼리 기록은 이용할 수 없습니다.

쿼리 승인

일부 MCP 클라이언트는 도구를 실행하기 전에 승인을 요청합니다. TablePlus는 execute_read_query를 읽기 전용으로, execute_query를 데이터 변경이 가능한 도구로 표시합니다. 따라서 Claude 같은 클라이언트는 승인 알림을 끄지 않는 한 execute_query를 호출할 때마다 권한을 요청합니다. 확인을 요청하지 않는 클라이언트도 있습니다.

데이터나 구조를 변경하는 쿼리에는 클라이언트의 동작과 별도로 TablePlus의 승인 설정도 적용됩니다.

  • Silent Mode 연결 상태에서 위험한 쿼리에 대한 승인 필요가 켜져 있으면 TablePlus 는 AI 에이전트 쿼리 승인 시트에 쿼리를 표시합니다. Allow 를 클릭하여 실행하거나 Deny 를 클릭하여 거부할 수 있습니다.
  • 다른 안전 모드 연결에서 안전 모드가 대신 확인을 요청하므로, 쿼리를 승인하거나 데이터베이스 비밀번호를 입력해야 합니다.

TablePlus 는 쿼리를 승인해야 할 때 화면에 나타납니다.

Approval needed for unsafe query를 끄면 Read & Write 권한이 있는 토큰으로 Silent Mode 연결의 데이터를 변경할 때 TablePlus가 확인을 요청하지 않습니다. 클라이언트가 데이터를 변경할 수 있는 범위를 제한하려면 Read Only 토큰을 사용하거나 토큰을 필요한 연결에만 허용하세요.

활동

Activity를 Settings > MCP에서 클릭하거나, Open Anything에서 MCP Activity를 선택하여 Integrations Activity 창을 엽니다.

MCP 클라이언트로부터의 요청 목록을 표시하는 통합 활동 창
MCP 활동 기록

도구 모음의 View 컨트롤을 사용하여 다음 옵션들 사이를 전환하세요:

  • Activity: 모든 요청의 기록을 포함하며, 상태, 시간, 카테고리, 토큰, 클라이언트 주소, 연결, 작업 및 쿼리를 표시합니다. 행을 선택하여 자세한 내용을 확인합니다. 검색 필드, 시간 범위 (Last 24 hours, Last 7 days, Last 30 days, All time) 및 토큰 메뉴를 사용하여 로그를 필터링합니다. Export CSV을 클릭하여 로그를 저장하거나, Clear Activity를 클릭하여 30 일 또는 7 일 이상 된 항목 또는 모든 항목을 삭제합니다.
  • 고객: 현재 연결된 고객 정보 (이름, 버전, 토큰, 주소, 연결 시간 및 마지막 활동 시간)를 표시합니다. 원하는 고객을 선택하고 Disconnect를 클릭하여 세션을 종료하고 실행 중인 요청을 취소합니다.

원격 접속

다른 기기의 MCP 클라이언트가 연결할 수 있도록 하려면 다음과 같이 설정합니다.

  1. Allow remote access (TLS)를 선택합니다. 서버는 이제 HTTPS 를 사용합니다.
  2. Export Certificate…를 클릭한 후 원격 기기에 tableplus-mcp.pem 파일을 신뢰할 수 있는 인증서로 설치합니다.
  3. 원격 클라이언트용 액세스 토큰을 만듭니다.
  4. Client Setup에서 Manual Setup…을 클릭하고 HTTP Server를 선택하여 엔드포인트를 확인한 후, 예시 https://your-mac.local:51003/mcp와 같은 주소를 클라이언트에 설정합니다.

원격 클라이언트는 토큰에 허용된 모든 연결에 접근할 수 있습니다. 토큰에 필요한 최소 권한만 부여하고 사용할 수 있는 연결을 명시적으로 제한하세요.