kl-mcp-client (Python)

Thư viện Python Client dùng để điều khiển trình duyệt Web thông qua Model Context Protocol (MCP). Hỗ trợ Camoufox anti-detect browser với persistent profile, fingerprint spoofing và proxy.

Cài đặt

# Core SDK
pip install kl-mcp-client

# Với Camoufox anti-detect browser
pip install kl-mcp-client[camoufox]
python -m camoufox fetch

Hướng dẫn Bắt đầu Nhanh

Chế độ Đồng bộ (Synchronous)

from kl_mcp_client.tools import MCPTools

tools = MCPTools()
tools.connect_mcp("http://localhost:8080/mcp")
sid = tools.create_session("ws://browser-host:9222")["sessionId"]
tools.open_page(sid, "https://google.com")
tools.screenshot(sid)
tools.close_session(sid)

Chế độ Bất đồng bộ (Asynchronous)

import asyncio
from kl_mcp_client.asyncio.tools import MCPTools

async def main():
    tools = MCPTools()
    tools.connect_mcp("http://localhost:8080/mcp")
    res = await tools.create_session("ws://browser-host:9222")
    sid = res["sessionId"]
    await tools.open_page(sid, "https://github.com")
    await tools.close_session(sid)

asyncio.run(main())

Camoufox Anti-Detect Browser

Module kl_mcp_client.camoufox quản lý Camoufox browser (Firefox-based) với khả năng chống phát hiện bot.

Local Mode — Persistent Profile

Dùng cho tự động hóa cần giữ session (cookies, localStorage, fingerprint) qua nhiều lần chạy.

from kl_mcp_client.camoufox import CamoufoxManager, CamoufoxConfig

cfg = CamoufoxConfig(
    profile_dir="~/.camoufox-profiles/account-1",
    proxy={
        "server": "http://proxy.example.com:8080",
        "username": "user",
        "password": "pass",
    },
    headless=True,
    locale="vi-VN",
    os_name="windows",       # Fingerprint giả lập Windows
    block_webrtc=True,        # Chặn WebRTC leak IP
)

with CamoufoxManager(cfg) as mgr:
    page = mgr.context.new_page()
    page.goto("https://example.com")

    # Cookies & localStorage tự động persist trong profile_dir
    print(page.title())
    print(page.evaluate("navigator.userAgent"))

    # Anti-detect verification
    assert page.evaluate("navigator.webdriver") == False

Server Mode — WS Endpoint cho MCP Server

Dùng cho Docker deployment hoặc kết nối remote.

from kl_mcp_client.camoufox import CamoufoxManager, CamoufoxConfig

cfg = CamoufoxConfig(
    mode="server",
    headless=True,
    host="0.0.0.0",       # Bind tất cả interface
)

with CamoufoxManager(cfg) as mgr:
    ws_endpoint = mgr.ws_endpoint
    # ws://127.0.0.1:RANDOM_PORT/TOKEN
    # Truyền cho MCP server: BROWSER_PLAYWRIGHT_WS=ws://...

CamoufoxConfig Options

Option	Type	Default	Mô tả
`mode`	`"local" \| "server"`	`"local"`	Local = Playwright trực tiếp. Server = WS endpoint
`profile_dir`	`str \| None`	`None`	Thư mục profile Firefox. `None` = tạm thời
`proxy`	`dict \| None`	`None`	`{"server": "...", "username": "...", "password": "..."}`
`headless`	`bool`	`True`	Chạy headless
`geoip`	`bool`	`False`	Tự detect geolocation từ proxy IP
`fingerprint`	`dict \| None`	`None`	Custom fingerprint. `None` = tự tạo random
`fingerprint_preset`	`bool \| dict \| None`	`None`	Dùng fingerprint thật thay vì random
`locale`	`str \| None`	`None`	Locale: `"en-US"`, `"vi-VN"`
`os_name`	`str \| None`	`None`	OS giả lập: `"windows"`, `"macos"`, `"linux"`
`block_images`	`bool`	`False`	Chặn hình ảnh
`block_webrtc`	`bool`	`False`	Chặn WebRTC leak
`block_webgl`	`bool`	`False`	Chặn WebGL fingerprint
`addons`	`list[str] \| None`	`None`	Đường dẫn tới Firefox extension XPI
`humanize`	`bool \| float \| None`	`None`	Mô phỏng di chuyển chuột con người
`enable_cache`	`bool \| None`	`None`	Browser disk cache
`port`	`int`	`0`	Port (server mode). `0` = random high port
`host`	`str`	`"127.0.0.1"`	Bind host (server mode)

Tài liệu API

Method	Mô tả	MCP Server
`connect_mcp(url)`	Kết nối tới MCP server	v1.0.0+
`create_session(cdpUrl)`	Tạo phiên browser	v1.0.0+
`close_session(sid)`	Đóng phiên	v1.0.0+
`open_page(sid, url)`	Mở URL	v1.0.0+
`get_html(sid)`	Lấy HTML	v1.0.0+
`get_clean_text(sid)`	Lấy text đã lọc tag	v1.0.0+
`screenshot(sid)`	Chụp màn hình (Base64)	v1.0.0+
`get_cookies(sid)`	Lấy cookies	v1.0.0+
`import_cookies(sid, cookies)`	Import cookies	v1.0.0+

AI Interaction

Method	Mô tả	MCP Server
`find_element_by_prompt(sid, prompt)`	Tìm phần tử bằng AI	v1.5.0+
`find_elements_by_prompt(sid, prompt)`	Tìm nhiều phần tử bằng AI	v1.6.1+
`find_element_context(sid, prompt)`	Tìm phần tử bằng context analysis	v1.6.1+
`click_by_prompt(sid, prompt)`	AI tìm và click	v1.6.1+
`extract_structured(sid, prompt)`	Trích xuất dữ liệu thành JSON	v1.6.1+
`parse_html_by_prompt(html, prompt)`	Parse HTML bằng AI	v1.6.1+

Input & Controls

Method	Mô tả	MCP Server
`click(sid, selector)`	Click phần tử	v1.0.0+
`click_to_text(sid, text)`	Click theo text	v1.0.0+
`type(sid, selector, text)`	Nhập text vào input	v1.0.0+
`send_text(sid, text, interval)`	Gõ phím human-like	v1.0.0+
`send_combo(sid, text)`	Tổ hợp phím (Ctrl+A)	v1.0.0+
`send_keys(sid, text)`	Gửi keystrokes	v1.0.0+
`scroll(sid, x, y)`	Cuộn trang	v1.0.0+
`drag_and_drop(sid, fx, fy, tx, ty)`	Kéo thả	v1.0.0+
`hover(sid, x, y)`	Di chuột	v1.0.0+

Tab Management

Method	Mô tả	MCP Server
`list_tabs(sid)`	Liệt kê tabs	v1.0.0+
`new_tab(sid, url)`	Mở tab mới	v1.0.0+
`switch_tab(sid, tabId)`	Chuyển tab	v1.0.0+
`close_tab(sid, tabId)`	Đóng tab	v1.0.0+
`current_tab(sid)`	Tab hiện tại	v1.0.0+
`get_current_url(sid)`	URL hiện tại	v1.0.0+

DOM & Element

Method	Mô tả	MCP Server
`get_dom_tree(sid)`	DOM tree	v1.0.0+
`get_clickable(sid)`	Các phần tử clickable	v1.0.0+
`find_element(sid, selector)`	Tìm 1 phần tử	v1.0.0+
`find_all(sid, selector)`	Tìm tất cả phần tử	v1.0.0+
`find_element_by_xpath(sid, xpath)`	Tìm bằng XPath	v1.0.0+
`find_element_by_text(sid, text)`	Tìm bằng text	v1.0.0+

Data Streaming

Method	Mô tả	MCP Server
`evaluate(sid, expression)`	Chạy JavaScript	v1.0.0+
`evaluate_stream_all(sid, expr, chunk, max)`	Stream dữ liệu lớn	v1.6.0+

File Upload

Method	Mô tả	MCP Server
`upload_file(sid, selector, file_path)`	Upload file (all-in-one)	v1.0.0+
`upload_file_to_server(file_path)`	Upload file lên server	v1.0.0+
`set_file_for_input(sid, selector, uploadId)`	Gắn file vào input	v1.0.0+

Ví dụ

Xem thư mục kl_mcp_client/examples/.

License

MIT

Metadata

Release files for kl-mcp-client 2.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kl-mcp-client 2.2.0
File	Size	Uploaded	Provenance
kl_mcp_client-2.2.0.tar.gz	26.1 kB	Oct 6, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for kl-mcp-client 2.2.0
File	Interpreter	ABI	Platform	Reset
kl_mcp_client-2.2.0-py3-none-any.whl 25.6 kB Oct 6, 2026 Without provenance	Python 3	none	any	Details

Total release size: 51.7 kB

Release files / kl_mcp_client-2.2.0.tar.gz

Download URL	kl_mcp_client-2.2.0.tar.gz
Size	26.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`c4e486163217ef47cfd219cdba2c7fb726c59fab041322b788bfebad243cf09b`
BLAKE2b-256 checksum How to use checksums	`db97c3a54acdc69f55dc72a02c11ad54bbaa35d24a2a6d3efb3c5c4be7ebd051`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.4`

Release files / kl_mcp_client-2.2.0-py3-none-any.whl

Download URL	kl_mcp_client-2.2.0-py3-none-any.whl
Size	25.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`235488b6856fbe0809a62c126902631df168511a271532a0608a16ffed284b1b`
BLAKE2b-256 checksum How to use checksums	`21a7ca8369562968e99d90fa57c7e8769a562f5833fe46abe596b7282e0b5b6c`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.4`

Security for kl-mcp-client 2.2.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.