Skip to main content
Glama
Archery MCP

Archery MCP

by lyj5812

Archery MCP

许可证:MIT

面向 Archery 的安全只读 Model Context Protocol Server。项目使用 Archery 用户名和密码认证,维护 Django Session 与 CSRF 状态,并向 AI 客户端提供实例查询、工单查询和受限 SQL 查询工具。

功能特性

  • 通过 Archery /authenticate/ 接口使用用户名和密码登录。

  • 自动处理 CSRF、复用 Session,并在会话过期后重新登录一次。

  • 使用 SQL AST 解析器对只读 SQL 做本地强校验。

  • 实例归属、查询权限、超时、行数限制、审计日志和数据脱敏继续由 Archery 服务端负责。

  • 不提供工单审批、变更 SQL 执行或任意 HTTP 代理工具。

  • 已在 Archery v1.14.0 上完成真实环境验证。

Related MCP server: sqldb-mcp-server

MCP 工具

工具

说明

archery_health

检查 Archery 连通性并识别版本

archery_login_status

验证配置的账号能否建立 Session

archery_list_instances

查询账号有权查看的实例,需要实例列表权限

archery_list_query_instances

查询账号可用于只读查询的实例

archery_list_databases

查询指定实例中的数据库

archery_query

执行一条受限只读查询,最多返回 5000 行

archery_export_query

将查询结果分批写入 CSV,默认不限制总行数

archery_list_workflows

查询当前账号可见的 SQL 工单

archery_workflow_status

查询工单状态

archery_workflow_detail

查询工单审核或执行明细

安装方式一:Windows EXE(推荐)

Windows 用户可以直接使用发布产物 archery-mcp.exe,无需安装 Python,也无需单独安装依赖。

MCP 客户端配置示例:

{
  "mcpServers": {
    "archery": {
      "command": "D:/tools/archery-mcp.exe",
      "env": {
        "ARCHERY_URL": "https://archery.example.com",
        "ARCHERY_USERNAME": "service-account",
        "ARCHERY_PASSWORD": "use-your-secret-store",
        "ARCHERY_VERIFY_TLS": "true",
        "ARCHERY_EXPORT_DIR": "D:/tools/archery-exports"
      }
    }
  }
}

EXE 使用标准输入输出与 MCP 客户端通信,因此不要直接双击运行。启动和停止由 MCP 客户端负责。

本地构建 EXE

维护者需要 Python 3.10 或更高版本执行构建,最终使用者不需要 Python:

.\build-exe.ps1 -Python python

脚本会依次安装构建依赖、执行全部单元测试、使用 PyInstaller 生成单文件 EXE,并通过真实 MCP stdio 握手检查全部工具。成功产物位于:

dist/archery-mcp.exe

GitHub Actions 中的“构建 Windows EXE”工作流支持手动触发,也会在推送 v* 标签时自动构建并上传 archery-mcp-windows-x64 Artifact。

安装方式二:Docker

使用方无需安装 Python,但需要安装 Docker。镜像使用标准输入输出传输 MCP 协议,因此必须使用 -i 保持 stdin 打开。

构建并验证镜像

Windows PowerShell:

.\build-docker.ps1 -Image archery-mcp:local -Python python

也可以手工执行:

docker build -t archery-mcp:local .
python scripts/smoke_test_docker.py archery-mcp:local

Docker MCP 客户端配置

下面的 -e ARCHERY_* 只传递变量名,实际值来自 MCP 客户端进程环境,不会出现在 Docker 命令行参数中:

{
  "mcpServers": {
    "archery": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--read-only",
        "--tmpfs",
        "/tmp:size=64m,mode=1777",
        "--security-opt",
        "no-new-privileges:true",
        "-e",
        "ARCHERY_URL",
        "-e",
        "ARCHERY_USERNAME",
        "-e",
        "ARCHERY_PASSWORD",
        "-e",
        "ARCHERY_VERIFY_TLS",
        "-e",
        "ARCHERY_TIMEOUT",
        "-e",
        "ARCHERY_EXPORT_DIR",
        "--volume",
        "D:/tools/archery-exports:/exports",
        "archery-mcp:local"
      ],
      "env": {
        "ARCHERY_URL": "https://archery.example.com",
        "ARCHERY_USERNAME": "service-account",
        "ARCHERY_PASSWORD": "use-your-secret-store",
        "ARCHERY_VERIFY_TLS": "true",
        "ARCHERY_TIMEOUT": "30",
        "ARCHERY_EXPORT_DIR": "/exports"
      }
    }
  }
}

项目也提供 docker-compose.yml。在宿主机设置所需环境变量后,可以执行:

docker compose build
docker compose run --rm archery-mcp

不要使用缺少 -i 的 docker run,否则容器无法接收 MCP 客户端发送的 stdio 消息。

安装方式三:Python

需要 Python 3.10 或更高版本。

git clone <仓库地址>
cd archery-mcp
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\python.exe -m pip install .

Linux 或 macOS:

./.venv/bin/python -m pip install .

环境变量

环境变量

说明

ARCHERY_URL

Archery 根地址,例如 https://archery.example.com

ARCHERY_USERNAME

最小权限服务账号用户名

ARCHERY_PASSWORD

服务账号密码

ARCHERY_VERIFY_TLS

是否校验 TLS 证书,默认为 true

ARCHERY_TIMEOUT

HTTP 超时时间,默认 30 秒,最大 120 秒

ARCHERY_EXPORT_DIR

CSV 导出目录,Python/EXE 默认是当前目录下的 exports

Python 方式的 MCP 客户端配置

Windows 示例:

{
  "mcpServers": {
    "archery": {
      "command": "D:/path/to/archery-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "archery_mcp.server"],
      "env": {
        "ARCHERY_URL": "https://archery.example.com",
        "ARCHERY_USERNAME": "service-account",
        "ARCHERY_PASSWORD": "use-your-secret-store",
        "ARCHERY_VERIFY_TLS": "true",
        "ARCHERY_EXPORT_DIR": "D:/path/to/archery-exports"
      }
    }
  }
}

不要将真实凭据提交到 Git。${ENV_VAR} 占位符是否生效取决于 MCP 客户端,建议通过客户端进程环境或密钥管理服务注入凭据。

查询安全

archery_query 只接受一条 SELECT、WITH 或集合查询,并拒绝:

  • 多条 SQL;

  • 新增、更新、删除、DDL 和管理命令;

  • FOR UPDATE 等锁查询;

  • 文件导入、文件读取和文件导出操作;

  • sleep、benchmark 等延迟或资源消耗函数;

  • 普通查询超过 5000 行的返回请求。

分页导出

archery_export_query 适合导出超过 Archery 单次查询上限的数据。默认每页查询 5000 行,不限制总行数,并持续分页到 Archery 返回不足一页为止。工具不会把大量数据返回给 AI,而是流式写入 CSV,只返回文件路径、实际行数、分页次数和是否因显式限制而截断。

示例参数:

{
  "instance_name": "read-replica",
  "database": "example",
  "sql": "select id, name from account order by id",
  "page_size": 5000,
  "max_rows": 0,
  "filename": "accounts.csv"
}

多页导出要求 SQL 顶层包含稳定且尽量唯一的 ORDER BY,例如 order by id。传入 SQL 不能自行包含 LIMIT 或 OFFSET,分页条件由 MCP 统一生成。CSV 使用 UTF-8 BOM 以兼容 Excel,并对 =、+、-、@ 等开头的文本增加前缀,降低 CSV 公式注入风险。

max_rows=0 表示不限制总行数;传入正数时可以主动设置本次导出上限。不限量导出可能持续占用 Archery 查询资源和本地磁盘,请确保 SQL 使用稳定排序,并监控导出目录容量。

导出文件只能写入 ARCHERY_EXPORT_DIR。Docker 模式必须把宿主机目录挂载到 /exports;Compose 默认将项目下的 exports 目录挂载进去。

CSV 可能包含敏感业务数据。请限制导出目录的操作系统访问权限,设置定期清理策略,不要把导出目录提交到 Git、打进镜像或暴露为公共下载目录。

本地 SQL 校验属于纵深防御,不能替代 Archery 或数据库权限。生产环境必须使用专用最小权限账号,优先关联只读数据库实例,并保持 Archery 的资源组、查询权限、超时、审计日志、行数限制和数据脱敏配置有效。

启用交互式 2FA 的账号无法用于机器登录。服务检测到 2FA 后会终止登录,应为 MCP 创建未启用交互式 2FA 的最小权限服务账号。

本地开发

python -m pip install -e ".[test]"
python -m pytest -q

提交代码前请阅读 贡献指南。安全问题请按 安全策略 处理。

许可证

本项目使用 MIT License。许可证文件保留标准英文法律文本。

Available Tools

10 tools
archery_export_queryA

将只读查询分批导出为 CSV;默认每页 5000 行,不限制总行数。

Inputs: sql (required), database (required), instance_name (required), schema, +3 more. Returns: object

archery_healthA

检查 Archery 是否可访问并返回版本;不执行登录。

Inputs: no named parameters. Returns: object

archery_list_databasesB

查询指定可读实例中的数据库;实例归属由 Archery 校验。

Inputs: instance_name (required). Returns: object

archery_list_instancesA

分页查询当前 Archery 账号有权查看的数据库实例。

Inputs: limit, offset, search. Returns: object

archery_list_query_instancesA

查询当前账号所在资源组中允许只读查询的实例。

Inputs: no named parameters. Returns: object

archery_list_workflowsC

分页查询当前账号有权查看的 SQL 工单。

Inputs: limit, offset, search. Returns: object

archery_login_statusA

使用配置的用户名和密码登录,确认账号可用于 MCP。

Inputs: no named parameters. Returns: object

archery_queryA

执行单条受限只读查询;最多返回 5000 行。

Inputs: sql (required), database (required), instance_name (required), limit, +1 more. Returns: object

archery_workflow_detailB

查询一个有权查看的 SQL 工单审核或执行明细。

Inputs: workflow_id (required). Returns: object

archery_workflow_statusB

查询一个有权查看的 SQL 工单当前状态。

Inputs: workflow_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools target distinct resources/actions, such as health, login, instance listing, querying, and workflow inspection. However, `list_instances` and `list_query_instances` overlap in scope (both list instances, with subtle permission differences), which could cause occasional misselection.

    Naming Consistency4/5

    The `archery_` prefix is used consistently, and most listing tools follow a `list_` pattern. Minor deviations exist with `query`, `export_query`, and `workflow_status`/`workflow_detail`, which don't follow a strict verb_noun structure, but the names remain readable and predictable.

    Tool Count5/5

    Ten tools provide a well-scoped set for interacting with Archery, covering health, authentication, instance discovery, querying, export, and workflow inspection without exceeding a manageable number.

    Completeness4/5

    The tool set covers the core read-oriented workflows: discovering instances/databases, running read-only queries, exporting results, and checking workflow status. Minor gaps exist, such as no tool for retrieving table schemas or creating SQL workflows, but these are acceptable for a read-focused MCP server.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Read-only SQL Server MCP server enabling safe database queries, table listing, and schema inspection with built-in security protections.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A read-only MCP server that exposes SQL database access to LLMs, supporting multiple database types, compact columnar results, pagination, and file export.
      7
      12 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server for exploring on-premises, multi-instance Microsoft SQL Server estates from AI clients, with read-only enforcement and Windows authentication support.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A security-first, read-only MCP server for AI assistants to safely query MySQL, PostgreSQL, and Redis with layered safety checks.
      1
      MIT