pentest-kb MCP Server

Penetration testing experience base MCP server. Based on MCP (Model Context Protocol), it provides tools such as retrieval, addition, and listing for accumulating and reusing hands-on penetration testing experience.

What problem does this project solve

Background pain points:

• Penetration testing experience is scattered across notes, chat logs, and personal memory, making it hard to retrieve and reuse; when encountering similar problems (such as WAF bypass, 403 bypass), you often have to search again from scratch

• Agents have no access to a personal experience base by default; when answering penetration testing questions, they can only rely on general knowledge, lacking hands-on experience support and tending to give vague, generic advice

• Experience cannot be accumulated or reused across scenarios, making it hard for individuals or teams to build a systematic body of knowledge

What this project solves:

• Unifies penetration testing experience into a PostgreSQL (Supabase) database with structured storage

• Connects the experience base to agents via the MCP protocol, letting agents directly search (search_experience), add (add_experience), and list (list_all_experiences) experience

• Retrieval is based on BM25 relevance ranking (jieba Chinese word segmentation), more accurate than simple fuzzy matching

• Lets agents answer in real-world scenarios based on their personal experience base rather than general knowledge alone

Related MCP server: Nümtema Private Knowledge MCP

Features

• search_experience(keyword, tags_filter): searches the experience base with BM25 relevance ranking (approved records only), supports Chinese word segmentation, returns Top 10; tags_filter allows precise filtering by scenario tags (e.g., ["WAF bypass"])

• add_experience(title, detail, scenario_tags, tool_code, tool_type, status): adds experience. status='draft' stores it as a pending-approval draft (default); status='approved' puts it directly into the base; before writing, an automatic desensitization check is performed (detects real IPs, domains, credentials, cloud provider AccessKeys, JWTs, private keys, phone numbers; rejects on match)

• list_all_experiences(limit, offset): paginated list of titles of all approved records in the experience base (default 50 per page, max 200)

• find_similar(title, detail): duplicate check, finds stored records similar to the given content

• get_experience(experience_id): gets the full content of one experience by id (title, detail, tags, tool code, status, etc.)

• update_experience(experience_id, title, detail, scenario_tags, tool_code, tool_type, status): updates fields of an experience (only updates passed-in fields; omitted fields remain unchanged; desensitization check is performed before modifying)

• list_pending_experiences(): lists pending-approval drafts and hints at stored records each draft may duplicate

• approve_experience(experience_id, merge_with_id): approves a draft; when merge_with_id is provided, merges it into the specified record (detail appended, tags merged, tool info completed) and then deletes the draft

• reject_experience(experience_id): rejects a draft (soft delete, the record is kept as rejected and can be restored)

• delete_experience(experience_id): soft-deletes an approved experience (status set to deleted, excluded from search, restorable)

• restore_experience(experience_id): restores a soft-deleted record (rejected draft → draft, deleted experience → approved)

• list_deleted_experiences(): lists all soft-deleted records (recycle bin), making it easy to restore or permanently clean up

• purge_experiences(days): physically deletes records soft-deleted for more than the specified number of days (default 30 days, irreversible, use with caution)

Experience accumulation and approval

To avoid verbose content and sensitive information leakage from automatic accumulation, a "semi-automatic accumulation + mandatory desensitization + manual approval" flow is used:

实战结束 → Agent 生成经验草稿（status='draft'，结构化 + 限长 + 脱敏）
        → 草稿进入待审批状态（不直接入库，不参与检索）
        → 用户审批（list_pending 查看 → approve / reject / merge）
        → 通过后才正式入库（status='approved'）

Desensitization line of defense: before writing, add_experience automatically detects real IP addresses, domains, emails, credentials (including Chinese "password/passphrase/secret/account" etc.), cloud provider AccessKeys (AWS/Aliyun/Tencent), JWTs, private key blocks, and phone numbers; on a match, the write is rejected and placeholders are required instead (e.g., <target URL>, <target domain>). Special IPs such as private/loopback/link-local addresses and whitelisted domains (example.com etc.) are allowed into the base.

Duplicate-check line of defense: during approval, list_pending_experiences automatically hints at stored records each draft may duplicate, and the user can choose to skip, merge, or still add.

Direct insertion vs. draft approval: add_experience supports status='approved' for direct insertion, used only for manual user-confirmed entry scenarios; AI workflows (see SKILL.md) must always generate draft drafts and go through approval, never direct insertion.

Dependencies

• Python 3.10+

• mcp (MCP Python SDK)

• psycopg2 (PostgreSQL driver)

• jieba (Chinese word segmentation, automatically loads the domain dictionary pentest_dict.txt in the root directory at startup)

• rank_bm25 (BM25 retrieval algorithm)

• A PostgreSQL database (e.g., Supabase)

Install dependencies:

pip install -r requirements.txt

The dependency list is in requirements.txt (version ranges are pinned; note that mcp must be 2.x).

Database initialization

Run schema.sql in the repository root directory against PostgreSQL (e.g., Supabase) (idempotent, can be run repeatedly):

# 方式一：Supabase 控制台 → SQL Editor → 粘贴 schema.sql 内容执行
# 方式二：命令行（需已配置 psql）
psql "$PENTEST_KB_DB_CONNECTION_STRING" -f schema.sql

The table structure is as follows (schema.sql is the single source of maintenance; the README does not repeat the SQL):

Optional: semantic search column (not used by the current code, reserved) To integrate vector semantic search, uncomment the trailing comment in schema.sql and run it (requires enabling the pgvector extension first).

Configuration

Database connection information is injected via environment variables; do not hardcode credentials in code:

MCP client configuration

Register the server in your MCP client, see mcp.example.json:

{
  "mcpServers": {
    "pentest-kb": {
      "command": "python",
      "args": ["/absolute/path/to/pentest_kb_mcp.py"],
      "env": {
        "PENTEST_KB_DB_HOST": "your-supabase-host.pooler.supabase.com",
        "PENTEST_KB_DB_PORT": "5432",
        "PENTEST_KB_DB_NAME": "postgres",
        "PENTEST_KB_DB_USER": "postgres.your-project-ref",
        "PENTEST_KB_DB_PASSWORD": "your-database-password"
      }
    }
  }
}

Usage

Call the tools in your MCP client, for example:

搜索：search_experience(keyword="WAF绕过")   # BM25 相关性排序
搜索+标签过滤：search_experience(keyword="绕过", tags_filter=["WAF绕过"])   # 只看 WAF 相关
新增（直接入库，仅手动操作）：add_experience(title="Nginx 403 绕过", detail="...", scenario_tags=["WAF绕过"], tool_type="burp", status="approved")
新增草稿：add_experience(title="...", detail="...")   # 默认 status='draft'，待审批
查重：find_similar(title="...", detail="...")
查看单条：get_experience(experience_id="...")
修改：update_experience(experience_id="...", detail="...")   # 只更新传入字段
查看草稿：list_pending_experiences()
审批：approve_experience(experience_id="...")   # 或 merge_with_id 合并
拒绝：reject_experience(experience_id="...")   # 软删除，可恢复
删除：delete_experience(experience_id="...")   # 软删除已审批经验
恢复：restore_experience(experience_id="...")
回收站：list_deleted_experiences()
清理：purge_experiences(days=30)   # 物理删除超期软删记录
列出：list_all_experiences(limit=50, offset=0)   # 分页

Skill encapsulation

Already wrapped as a custom Skill, located in SKILL.md in the project root directory, organized into six phases by execution flow:

• Phase 1: Intent determination

• Phase 2: Information gathering first

• Phase 3: Database lookup trigger

• Phase 4: Result citation and answering

• Phase 5: Execution and exemption rules

• Phase 6: Experience accumulation

Put SKILL.md into the custom Skill directory to load it.

Security notes

• Database credentials are injected only via environment variables; the repository contains no real connection information

• Rotate the database password regularly and avoid using weak passwords