Archery MCP

Name: Archery MCP
Author: itzhouq

제작자: itzhouq버전 0.1.1i★ –i내 컴퓨터에서 실행

레지스트리 이름io.github.itzhouq/archery-mcp

설치

개요

제작자가 쓴 설명(영어 원문)

Read-only MCP server for the Archery SQL audit platform: production schema and release SQL checks

PopNx MCP의 세 기둥

이 세 가지는 절대 하나의 점수로 합치지 않아요. 의견, 측정, 인기는 서로 다른 것이니까요.

사용자 의견i아직 리뷰가 없어요리뷰는 다음 단계에서 계정 기능과 함께 열려요
우리의 기본 점검i1개 중 1개 통과공개된 정보로 점검했으며, 코드는 아직 스캔하지 않았어요
사용 정도i아직 측정 안 함★ –

할 수 있는 일

이 서버는 아직 쉬운 말로 된 요약을 쓰지 못했어요. 아래는 레지스트리에서 읽어 온 사실이에요.

연결 방식: 내 컴퓨터에서 실행
전송 방식: stdio
카테고리: 데이터베이스 및 데이터셋
입력해야 할 값: ARCHERY_BASE_URL, ARCHERY_USERNAME, ARCHERY_PASSWORD, ARCHERY_TOTP_SECRET, ARCHERY_INSTANCE_NAME, ARCHERY_DB_NAME

설치

쓰고 있는 AI 앱을 고른 다음 설정을 복사하세요.

설치하기 전에

기본 점검: 1개 중 1개 통과
내 컴퓨터에서 내 사용자 계정의 권한(파일, 네트워크, 앱)으로 실행돼요.
직접 입력할 값: ARCHERY_BASE_URL, ARCHERY_USERNAME, ARCHERY_PASSWORD, ARCHERY_TOTP_SECRET, ARCHERY_INSTANCE_NAME, ARCHERY_DB_NAME, ARCHERY_SCHEMA_NAME, ARCHERY_QUERY_LIMIT

비밀로 표시된 값은 내 계정의 열쇠예요. 절대 다른 사람과 공유하거나 채팅에 붙여 넣지 마세요.

필요한 것

PyPIPython의 uv 설치(uvx 명령어용)

어떤 앱을 쓰세요?

ClaudeClaude CodeCursorVS CodeChatGPT

위에서 앱을 고르세요. 기억해 두었다가 다음부터는 버튼에 “…에 설치”라고 표시해요.

Claude Desktop → Settings → Developer → Edit Config를 열고 claude_desktop_config.json에 이 내용을 붙여 넣으세요

{
  "mcpServers": {
    "archery": {
      "command": "uvx",
      "args": [
        "archery-mcp"
      ],
      "env": {
        "ARCHERY_BASE_URL": "your-value",
        "ARCHERY_USERNAME": "your-value",
        "ARCHERY_PASSWORD": "your-value",
        "ARCHERY_TOTP_SECRET": "your-value",
        "ARCHERY_INSTANCE_NAME": "your-value",
        "ARCHERY_DB_NAME": "your-value",
        "ARCHERY_SCHEMA_NAME": "your-value",
        "ARCHERY_QUERY_LIMIT": "your-value"
      }
    }
  }
}

터미널에서 이 명령어를 실행하세요

claude mcp add archery --env ARCHERY_BASE_URL=your-value --env ARCHERY_USERNAME=your-value --env ARCHERY_PASSWORD=your-value --env ARCHERY_TOTP_SECRET=your-value --env ARCHERY_INSTANCE_NAME=your-value --env ARCHERY_DB_NAME=your-value --env ARCHERY_SCHEMA_NAME=your-value --env ARCHERY_QUERY_LIMIT=your-value -- uvx archery-mcp

실행하기 전에 빈 값을 채워 주세요.

Cursor에서 열기

또는 설정을 직접 복사하기

프로젝트의 .cursor/mcp.json 또는 ~/.cursor/mcp.json에 붙여 넣으세요

{
  "mcpServers": {
    "archery": {
      "command": "uvx",
      "args": [
        "archery-mcp"
      ],
      "env": {
        "ARCHERY_BASE_URL": "your-value",
        "ARCHERY_USERNAME": "your-value",
        "ARCHERY_PASSWORD": "your-value",
        "ARCHERY_TOTP_SECRET": "your-value",
        "ARCHERY_INSTANCE_NAME": "your-value",
        "ARCHERY_DB_NAME": "your-value",
        "ARCHERY_SCHEMA_NAME": "your-value",
        "ARCHERY_QUERY_LIMIT": "your-value"
      }
    }
  }
}

브라우저가 앱을 열지 물어본 다음, 앱이 설정을 보여 주고 확인을 요청해요. 키 값은 비워 두니 직접 입력하세요.

VS Code에서 열기

또는 설정을 직접 복사하기

프로젝트의 .vscode/mcp.json에 붙여 넣으세요

{
  "servers": {
    "archery": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "archery-mcp"
      ],
      "env": {
        "ARCHERY_BASE_URL": "your-value",
        "ARCHERY_USERNAME": "your-value",
        "ARCHERY_PASSWORD": "your-value",
        "ARCHERY_TOTP_SECRET": "your-value",
        "ARCHERY_INSTANCE_NAME": "your-value",
        "ARCHERY_DB_NAME": "your-value",
        "ARCHERY_SCHEMA_NAME": "your-value",
        "ARCHERY_QUERY_LIMIT": "your-value"
      }
    }
  }
}

브라우저가 앱을 열지 물어본 다음, 앱이 설정을 보여 주고 확인을 요청해요. 키 값은 비워 두니 직접 입력하세요.

이 서버는 내 컴퓨터에서 실행되는데, ChatGPT는 인터넷에 있는 서버에만 연결할 수 있어요. 다른 앱을 고르세요.

선택한 앱은 이 기기의 쿠키에만 저장돼요. 계정은 필요 없어요.

직접 입력할 값

ARCHERY_BASE_URL 필수 env
Base URL of your Archery deployment, e.g. https://archery.example.com
ARCHERY_USERNAME 필수 env
Archery account username (use a dedicated least-privilege account)
ARCHERY_PASSWORD 비밀 필수 env
Archery account password
ARCHERY_TOTP_SECRET 비밀 env
Base32 TOTP secret if the account enables Google Authenticator 2FA
ARCHERY_INSTANCE_NAME 필수 env
Archery instance name to lock the server to
ARCHERY_DB_NAME 필수 env
Database name to lock the server to
ARCHERY_SCHEMA_NAME env
Schema name (PostgreSQL usually 'public'; leave empty for MySQL)
ARCHERY_QUERY_LIMIT env
Default row limit when the query tool is called without limit; 0 delegates the max to Archery

이 설정은 제작자의 레지스트리 정보로 만들었어요. README와 다르면 README를 따르세요.

할 수 있는 일

내 컴퓨터에서 실행돼요. 설치하면 AI 앱에 도구 목록이 나타나요.

기본 점검i

누구나 볼 수 있는 정보를 점검했고, 코드는 읽지 않았어요. 해당하지 않는 항목은 개수에서 뺐어요. · 2026년 11월 7일 점검

✓ 통과
제작자와 저장소 일치
레지스트리 이름이 GitHub 계정 itzhouq 기준으로 확인되었고, 이 계정이 저장소를 소유하고 있어요
… 아직 점검 안 함
계속 관리되고 있음
아직 GitHub에서 이 저장소를 읽어 오지 않았어요
… 아직 점검 안 함
라이선스 있음
아직 GitHub에서 이 저장소를 읽어 오지 않았어요
– 해당 없음
엔드포인트 응답
내 컴퓨터에서 실행되는 서버라 인터넷 엔드포인트가 없어요
– 해당 없음
OAuth로 로그인
내 컴퓨터에서 실행되며, 대신 로컬 설정을 사용해요
… 아직 점검 안 함
도구 설명에 숨겨진 지시 없음
내 컴퓨터에서 실행돼요. 도구 목록은 인터넷 엔드포인트가 있는 서버에서만 읽을 수 있어요

데이터베이스 및 데이터셋 카테고리의 다른 서버와 비교i

이 카테고리의 다른 서버 954개 중 0%보다 스타가 많아요
이 카테고리의 다른 서버 954개 중 66%보다 최근에 레지스트리에 공개됐어요
기본 점검 결과가 이 카테고리의 다른 서버 954개 중 100%와 같거나 더 좋아요

레지스트리에서 이 카테고리의 활성 서버 전체와 비교했어요. 스타는 게시자가 저장소를 소유한 경우에만 세요.

자주 묻는 질문

Archery MCP, 안전한가요?

해당하는 기본 점검 1개 중 1개를 통과했어요. 코드는 읽지 않았어요. 키나 토큰을 넣기 전에 서버가 어떤 권한을 요구하는지 확인하고, 꼭 필요한 권한만 있는 키를 쓰세요.

어떤 키나 코드가 필요한가요?

입력해야 할 값: ARCHERY_BASE_URL, ARCHERY_USERNAME, ARCHERY_PASSWORD, ARCHERY_TOTP_SECRET, ARCHERY_INSTANCE_NAME, ARCHERY_DB_NAME

내 컴퓨터에서 실행되나요, 클라우드에서 실행되나요?

내 컴퓨터에서 실행돼요. AI 앱이 필요할 때 실행하고, 데이터는 제작자의 서버를 거치지 않아요(서버 자체가 온라인 서비스를 호출하는 경우는 제외).

아직 관리되고 있나요?

GitHub 저장소는 마지막으로 – 변경됐고, 최신 버전(0.1.1)은 31일 전 레지스트리에 올라왔어요.

어떤 앱에서 쓸 수 있나요?

Claude Desktop, Claude Code, Cursor, VS Code처럼 MCP를 지원하는 앱에서 쓸 수 있어요. 내 컴퓨터에 Python (uv)도 있어야 해요.

대신 쓸 수 있는 건 뭐가 있나요?

같은 카테고리에는: Supabase, MongoDB MCP Server, Elasticsearch MCP Server

대안

같은 카테고리에서 다른 제작자가 만든 서버예요. 스타 순으로 정렬했어요.

카드 보는 법:★ GitHub 스타i세 기둥: 리뷰 · 점검 · 사용 정도i업데이트 = 최신 버전을 레지스트리에 공개한 날i

Supabase

제작자: supabase

MCP server for interacting with the Supabase platform

컴퓨터 또는 클라우드★ 2,993Apache-2.0어제 업데이트

설치

MongoDB MCP Server

제작자: mongodb-js

MongoDB Model Context Protocol Server

내 컴퓨터에서 실행★ 1,157Apache-2.0그저께 업데이트

설치

Elasticsearch MCP Server

제작자: cr7258

MCP server for interacting with Elasticsearch

내 컴퓨터에서 실행★ 315Apache-2.014개월 전 업데이트

설치

제작자의 README

README 열기

제작자의 저장소에서 쓰인 그대로 가져왔어요. PopNx MCP가 검토하거나 보증한 내용이 아니에요. HTML, 이미지, 스크립트는 제거했어요. 링크를 누르면 이 사이트를 벗어나요.

archery-mcp

Unofficial read-only MCP server for [Archery](https://github.com/hkadb/archery) — let your AI coding agent inspect production table schema and validate release SQL through your own Archery platform, with permissions, row limits and data masking still enforced by Archery itself.

中文：archery-mcp 是一个 MCP Server，把 Archery SQL 审核平台的在线查询与 SQL 检查能力带给 AI 编码助手（Claude Code、Cursor、Codex CLI 等）。AI 在写代码时可以直接查看线上表结构、验证数据特征、检查上线 SQL 规范，而不需要你手动比对环境差异。

[!IMPORTANT]

- 本项目与 Archery 官方无隶属关系，是独立的非官方客户端；

- 本项目按"现状"提供（MIT License）。使用者须自行取得公司授权并遵守公司数据安全规定，作者不对违规使用及其后果负责；

- 安全模型：本 MCP 不在本地过滤 SQL 或遮蔽数据，权限、行数上限、超时与脱敏完全由你自己的 Archery 平台执行——请给 MCP 配置专用的最小权限账号（见安全模型）。

为什么做这个

日常迭代业务系统时，常见的三个痛点：

test 和 prod 的表结构、索引可能不一致。AI 拿着过时或想当然的表结构写代码、写上线脚本，错误要到上线前人工比对时才发现；
上线脚本靠人工比对环境差异来写。版本迭代需要 DDL/DML 时，你得手动 DESC 生产表、核对索引，再让 AI 照着写——重复、低效、易错；
有些数据清洗依赖生产数据的真实特征（脏数据分布、边界记录、字段实际取值），test 环境的数据无法完整呈现。

这些问题的共同解法是：让 AI 在编码工作流中随时、只读地"看见"生产库——而不是绕过审批直连数据库。如果公司已经在用 Archery 管理 SQL 查询和上线工单，权限、审计、脱敏、工单流都已经在 Archery 里，那么把 Archery 的查询能力封装成 MCP 工具，就是最稳妥的路径。这正是 archery-mcp 做的事。

工作原理

flowchart LR

服务端锁定目标：启动时通过环境变量固定实例、数据库和模式，AI 调用工具时不能切换查询目标，防止模型误连其他库；
策略下沉 Archery：SQL 是否可执行、返回行数、超时、脱敏、审计全部由 Archery 配置和账号权限决定，本 MCP 原样转发、原样返回，不做二次过滤；
sql_check 双路检查：内置规范（本地静态规则）+ Archery 平台检查（/api/v1/workflow/sqlcheck/）合并出结论，平台不可用时优雅降级。

工具列表

工具	说明
`list_tables(keyword="")`	列出锁定目标库中的表，可按关键字过滤
`describe_table(table_name)`	查看表结构（字段、类型、默认值、注释）
`query(sql, limit=None)`	通过 Archery 在线查询执行 SQL（只读，原样转发）
`query_history(limit=20, search="")`	查看当前 Archery 账号的查询历史
`sql_check(sql)`	检查上线 SQL：内置规范 + Archery 平台检查，只检查不执行

sql_check 内置规范要点（规则实现在 src/archery_mcp/sql_rules.py，errlevel 语义与 Archery 一致：0 通过 / 1 警告 / 2 错误）：

上线 SQL 仅支持 DML/DDL，不接受 SELECT（错误）；
UPDATE/DELETE 必须带 WHERE 条件（错误）；
存储过程 / 函数 / 触发器 / DO 块不接受（错误）；
事务控制语句（BEGIN/COMMIT 等）警告——平台会逐条执行并自动提交；
临时表、CTE/窗口函数/CREATE TABLE AS、TRUNCATE、DROP DATABASE/SCHEMA、混提 DDL 与 DML 均给出警告。

与其他方案的区别

方案	权限/审计/脱敏	目标控制	上线 SQL 检查
直连生产库的数据库 MCP	❌ 绕过平台	依赖模型自觉	❌
archery-mcp-server（全量封装 Archery API）	✅ 走 Archery	客户端传参，多实例自由切换	平台检查
archery-mcp（本项目）	✅ 走 Archery	服务端锁定单一目标，模型不可切换	内置规范 + 平台检查双路合并

定位差异：archery-mcp 面向"嵌入日常迭代开发流"——固定目标、只读优先、上线前检查，牺牲灵活性换取更低的误操作面。

快速开始

前置条件：Python 3.11+，一个能访问 Archery 的账号（建议专用最小权限账号），且账号有在线查询权限。

方式一：uvx（推荐，无需安装）

uvx archery-mcp

方式二：pip

pip install archery-mcp

方式三：源码

git clone https://github.com/itzhouq/archery-mcp

cd archery-mcp python -m pip install -e .

MCP 客户端配置

以 Claude Code 为例，在项目根目录 .mcp.json（或全局配置）中加入：

"mcpServers": { "archery_mcp": { "command": "uvx", "args": ["archery-mcp"], "env": { "ARCHERY_BASE_URL": "https://archery.example.com", "ARCHERY_USERNAME": "你的 Archery 用户名", "ARCHERY_PASSWORD": "你的 Archery 密码", "ARCHERY_TOTP_SECRET": "", "ARCHERY_INSTANCE_NAME": "prod-app-db", "ARCHERY_DB_NAME": "app_db", "ARCHERY_SCHEMA_NAME": "public", "ARCHERY_QUERY_LIMIT": "100" } } } }

Cursor / Codex CLI 等其他客户端使用相同的 command / args / env 结构。保存后重启客户端即可。凭据只经进程环境变量传递，不要写入任何会提交的文件。

配置项

环境变量	必填	说明	默认
`ARCHERY_BASE_URL`	✅	Archery 部署地址，如 `https://archery.example.com`	—
`ARCHERY_USERNAME`	✅	Archery 用户名（建议专用最小权限账号）	—
`ARCHERY_PASSWORD`	✅	Archery 密码	—
`ARCHERY_TOTP_SECRET`	—	账号开启 Google 身份验证器时的 base32 密钥（不是六位验证码）	空
`ARCHERY_INSTANCE_NAME`	✅	锁定的 Archery 实例名（须在账号可访问列表内）	—
`ARCHERY_DB_NAME`	✅	锁定的数据库名	—
`ARCHERY_SCHEMA_NAME`	—	锁定的模式名；PostgreSQL 通常填 `public`，MySQL 可留空	`public`
`ARCHERY_QUERY_LIMIT`	—	`query` 未传 `limit` 时的默认行数；`0` 表示交给 Archery 按账号权限使用最大限制	`100`

安全模型与免责声明

由 Archery 负责的部分（本 MCP 原样委托，不做本地重复实现）：

实例/库/表的访问权限与资源组隔离；
SQL 可执行性检查、高危语句正则（critical_ddl_regex）；
查询返回行数上限、查询超时；
数据脱敏规则（is_masked 会随查询结果返回）；
查询审计与历史（query_history 工具可直接查看）。

由 MCP 锁定的部分：

查询目标（实例/库/模式）在服务端配置中固定，工具调用不可切换；
凭据只通过环境变量传递，不落盘、不写日志。

部署建议：

为 MCP 创建专用 Archery 账号，不要用管理员账号；
只分配目标资源组/实例/库的查询权限；
在 Archery 中配置数据脱敏规则；
定期审计 Archery 查询历史；
sql_check 需要账号在 Archery 的 API 用户白名单（api_user_whitelist）内并拥有上线权限（sql.sql_submit）；不可用时本地规范结果仍会返回。

免责声明：本项目按"现状"提供，不含任何担保。使用本工具访问生产数据库前，请确认你已获得公司授权、遵守公司数据安全与合规规定。因违反公司规定或平台策略使用本工具导致的任何后果由使用者自行承担。

本地开发与验证

python -m pip install -e ".[dev]"

python -m pytest -q # 46 个测试，全部 Mock，不访问真实 Archery ruff check src tests scripts bash scripts/check_sensitive.sh # 敏感信息扫描

对真实 Archery 的冒烟验证（会登录并执行只读查询）：

ARCHERY_BASE_URL="https://archery.example.com" \

ARCHERY_USERNAME="你的用户名" \ ARCHERY_PASSWORD="你的密码" \ python scripts/smoke_readonly.py # 表清单 → 表结构 → SELECT * python scripts/smoke_sql_check.py # 上线 SQL 检查（只检查不执行） python scripts/smoke_mcp_stdio.py # MCP stdio 全链路

架构与设计决策的完整说明见 docs/ARCHITECTURE.md，参与开发见 CONTRIBUTING.md。

FAQ

登录报"用户名或密码错误"，但网页能正常登录？ 账号大概率开启了两步验证。设置 ARCHERY_TOTP_SECRET 为 Google 身份验证器对应的 base32 密钥（绑定时的那串大写字母，不是实时的六位验证码）。

`sql_check` 提示"平台检查未执行"？ 账号需要在 Archery 系统配置 api_user_whitelist（API 用户白名单）内，并拥有 sql.sql_submit 权限。本地内置规范结果不受影响。

查询被 Archery 拒绝？ 检查账号在 Archery 中的资源组、实例与库权限，以及该账号的查询行数限制配置。MCP 会原样返回 Archery 的错误信息。

支持哪些 Archery 版本？ 针对 Archery v1.10.0 开发与实测。其他版本的 Web 端点行为未验证，遇到不兼容欢迎提 Issue（附上版本号与脱敏后的错误信息）。

为什么不在 MCP 侧过滤敏感字段？ 本地过滤会制造"看起来安全"的错觉，而权限与脱敏的真正执行点在 Archery。MCP 侧重复实现只会两套规则互相打架；把策略收敛到平台一处，审计才有一致的依据。这也是本项目的核心设计决策（详见 docs/ARCHITECTURE.md）。

Roadmap

跨实例 schema diff：对比 test 与 prod 的表结构/索引差异，直接生成变更清单（本项目最初要解决的痛点，欢迎讨论设计）；
SQL 工单状态查询（只读）；
多目标白名单（target → 固定的实例/库/模式组合）；
内置规范规则可配置化。

致谢

Archery —— 本项目封装的平台，SQL 审核与查询治理能力的真正执行者；
ckall/archery-mcp-server —— 同生态的另一个优秀实现，思路有别，可对照选用。

关于作者

itzhouq，独立开发者，在 itzhouq.cn 记录 build in public 日常，做的小工具都收录在工具页。

本项目的开源复盘：让 AI 只读"看见"生产库：archery-mcp 开源复盘

License

MIT

Archery MCP

개요

PopNx MCP의 세 기둥

할 수 있는 일

설치

설치하기 전에

직접 입력할 값

할 수 있는 일

기본 점검i

제작자와 저장소 일치

계속 관리되고 있음

라이선스 있음

엔드포인트 응답

OAuth로 로그인

도구 설명에 숨겨진 지시 없음

데이터베이스 및 데이터셋 카테고리의 다른 서버와 비교i

자주 묻는 질문

대안

Supabase

MongoDB MCP Server

Elasticsearch MCP Server

제작자의 README

archery-mcp

为什么做这个

工作原理

工具列表

与其他方案的区别

快速开始

MCP 客户端配置

配置项

安全模型与免责声明

本地开发与验证

FAQ

Roadmap

致谢

关于作者

License