mcp-hcaptcha 2026.10.8.0__tar.gz

mcp_hcaptcha-2026.10.8.0/.env.example

@@ -0,0 +1,6 @@
+ACEDATACLOUD_API_TOKEN=
+ACEDATACLOUD_API_BASE_URL=https://api.acedata.cloud
+HCAPTCHA_REQUEST_TIMEOUT=120
+MCP_TRANSPORT=stdio
+MCP_SERVER_NAME=hcaptcha
+LOG_LEVEL=INFO

mcp_hcaptcha-2026.10.8.0/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.py[cod]

mcp_hcaptcha-2026.10.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AceDataCloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_hcaptcha-2026.10.8.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: mcp-hcaptcha
+Version: 2026.10.8.0
+Summary: MCP server for AceDataCloud hCaptcha captcha APIs
+Project-URL: Homepage, https://github.com/AceDataCloud/MCPs
+Project-URL: Documentation, https://platform.acedata.cloud/services/018c653e-4f1b-433f-82f9-732ef2767040?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=hcaptcha_mcp_package_quick_start
+Project-URL: Repository, https://github.com/AceDataCloud/MCPs
+Project-URL: Issues, https://github.com/AceDataCloud/MCPs/issues
+Author-email: AceDataCloud <support@acedata.cloud>
+Maintainer-email: AceDataCloud <support@acedata.cloud>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acedata,captcha,hcaptcha,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: mcp<2,>=1.2.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: redis<7,>=5.0.0
+Provides-Extra: all
+Requires-Dist: build>=1.2.0; extra == 'all'
+Requires-Dist: mypy>=1.10.0; extra == 'all'
+Requires-Dist: pre-commit>=3.7.0; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
+Requires-Dist: pytest>=8.0.0; extra == 'all'
+Requires-Dist: respx>=0.21.0; extra == 'all'
+Requires-Dist: ruff>=0.4.0; extra == 'all'
+Requires-Dist: twine>=5.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: release
+Requires-Dist: build>=1.2.0; extra == 'release'
+Requires-Dist: twine>=5.0.0; extra == 'release'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Requires-Dist: respx>=0.21.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+<!-- Generated by scripts/marketing_readmes.py from README.md; do not edit. -->
+# MCP HCaptcha Server
+
+A Model Context Protocol (MCP) server for AceDataCloud's hCaptcha captcha-solving APIs.
+
+## Features
+- Solve hCaptcha image challenges and retrieve hCaptcha site tokens.
+- Shared async task polling via `/captcha/tasks`
+- Bearer-token authentication through AceDataCloud
+
+## Connect locally
+
+Use the local stdio package and an AceDataCloud API token. The public hosted HTTPS endpoint could not be verified, so this README does not offer it as a connection option. The local MCP process still calls AceDataCloud's API; it does not run the underlying service offline.
+
+Get an API credential through [AceDataCloud Platform](https://platform.acedata.cloud?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=hcaptcha_mcp_package_platform), keep it out of committed files, and review current pricing before a billable call.
+
+### Local stdio
+
+Install the package and give the local process an API token:
+
+```bash
+python -m pip install mcp-hcaptcha
+export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
+mcp-hcaptcha
+```
+
+For Claude Desktop local MCP, merge this entry into the file opened by its developer settings (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS). `uvx` requires [uv](https://docs.astral.sh/uv/) on `PATH`:
+
+```json
+{
+  "mcpServers": {
+    "hcaptcha": {
+      "command": "uvx",
+      "args": ["mcp-hcaptcha"],
+      "env": {"ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"}
+    }
+  }
+}
+```
+
+Keep this user-level file private. Self-hosted HTTP uses `mcp-hcaptcha --transport http --port 8000`; expose it only with suitable network and TLS controls. Local execution still calls the AceDataCloud API.
+
+### Check the connection
+
+Confirm that the MCP client loads its tools. `hcaptcha_get_usage_guide` returns reference information; it does not prove downstream API access or balance. A real service request can be billed. If it returns 401, check the API token; if it returns 403 or an account/balance error, read that response before retrying.
+
+## Tools
+- `hcaptcha_recognize` — Recognize hCaptcha image challenges
+- `hcaptcha_get_token` — Get an hCaptcha token for a website, optionally with `rqdata`
+- `hcaptcha_get_task` — Poll a captcha task result
+- `hcaptcha_get_usage_guide` — Get hCaptcha usage guide
+- `hcaptcha_get_api_info` — Get hCaptcha API information
+
+## Service details
+
+<!-- canonical-documentation -->
+[Service details](https://platform.acedata.cloud/services/018c653e-4f1b-433f-82f9-732ef2767040?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=hcaptcha_mcp_package_quick_start)

mcp_hcaptcha-2026.10.8.0/README.md

@@ -0,0 +1,56 @@
+# MCP HCaptcha Server
+
+A Model Context Protocol (MCP) server for AceDataCloud's hCaptcha captcha-solving APIs.
+
+## Features
+- Solve hCaptcha image challenges and retrieve hCaptcha site tokens.
+- Shared async task polling via `/captcha/tasks`
+- Bearer-token authentication through AceDataCloud
+
+## Connect locally
+
+Use the local stdio package and an AceDataCloud API token. The public hosted HTTPS endpoint could not be verified, so this README does not offer it as a connection option. The local MCP process still calls AceDataCloud's API; it does not run the underlying service offline.
+
+Get an API credential through [AceDataCloud Platform](https://platform.acedata.cloud?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=hcaptcha_mcp_readme_platform), keep it out of committed files, and review current pricing before a billable call.
+
+### Local stdio
+
+Install the package and give the local process an API token:
+
+```bash
+python -m pip install mcp-hcaptcha
+export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
+mcp-hcaptcha
+```
+
+For Claude Desktop local MCP, merge this entry into the file opened by its developer settings (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS). `uvx` requires [uv](https://docs.astral.sh/uv/) on `PATH`:
+
+```json
+{
+  "mcpServers": {
+    "hcaptcha": {
+      "command": "uvx",
+      "args": ["mcp-hcaptcha"],
+      "env": {"ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"}
+    }
+  }
+}
+```
+
+Keep this user-level file private. Self-hosted HTTP uses `mcp-hcaptcha --transport http --port 8000`; expose it only with suitable network and TLS controls. Local execution still calls the AceDataCloud API.
+
+### Check the connection
+
+Confirm that the MCP client loads its tools. `hcaptcha_get_usage_guide` returns reference information; it does not prove downstream API access or balance. A real service request can be billed. If it returns 401, check the API token; if it returns 403 or an account/balance error, read that response before retrying.
+
+## Tools
+- `hcaptcha_recognize` — Recognize hCaptcha image challenges
+- `hcaptcha_get_token` — Get an hCaptcha token for a website, optionally with `rqdata`
+- `hcaptcha_get_task` — Poll a captcha task result
+- `hcaptcha_get_usage_guide` — Get hCaptcha usage guide
+- `hcaptcha_get_api_info` — Get hCaptcha API information
+
+## Service details
+
+<!-- canonical-documentation -->
+[Service details](https://platform.acedata.cloud/services/018c653e-4f1b-433f-82f9-732ef2767040?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=hcaptcha_mcp_readme_quick_start)

mcp_hcaptcha-2026.10.8.0/README.pypi.md

@@ -0,0 +1,57 @@
+<!-- Generated by scripts/marketing_readmes.py from README.md; do not edit. -->
+# MCP HCaptcha Server
+
+A Model Context Protocol (MCP) server for AceDataCloud's hCaptcha captcha-solving APIs.
+
+## Features
+- Solve hCaptcha image challenges and retrieve hCaptcha site tokens.
+- Shared async task polling via `/captcha/tasks`
+- Bearer-token authentication through AceDataCloud
+
+## Connect locally
+
+Use the local stdio package and an AceDataCloud API token. The public hosted HTTPS endpoint could not be verified, so this README does not offer it as a connection option. The local MCP process still calls AceDataCloud's API; it does not run the underlying service offline.
+
+Get an API credential through [AceDataCloud Platform](https://platform.acedata.cloud?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=hcaptcha_mcp_package_platform), keep it out of committed files, and review current pricing before a billable call.
+
+### Local stdio
+
+Install the package and give the local process an API token:
+
+```bash
+python -m pip install mcp-hcaptcha
+export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
+mcp-hcaptcha
+```
+
+For Claude Desktop local MCP, merge this entry into the file opened by its developer settings (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS). `uvx` requires [uv](https://docs.astral.sh/uv/) on `PATH`:
+
+```json
+{
+  "mcpServers": {
+    "hcaptcha": {
+      "command": "uvx",
+      "args": ["mcp-hcaptcha"],
+      "env": {"ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"}
+    }
+  }
+}
+```
+
+Keep this user-level file private. Self-hosted HTTP uses `mcp-hcaptcha --transport http --port 8000`; expose it only with suitable network and TLS controls. Local execution still calls the AceDataCloud API.
+
+### Check the connection
+
+Confirm that the MCP client loads its tools. `hcaptcha_get_usage_guide` returns reference information; it does not prove downstream API access or balance. A real service request can be billed. If it returns 401, check the API token; if it returns 403 or an account/balance error, read that response before retrying.
+
+## Tools
+- `hcaptcha_recognize` — Recognize hCaptcha image challenges
+- `hcaptcha_get_token` — Get an hCaptcha token for a website, optionally with `rqdata`
+- `hcaptcha_get_task` — Poll a captcha task result
+- `hcaptcha_get_usage_guide` — Get hCaptcha usage guide
+- `hcaptcha_get_api_info` — Get hCaptcha API information
+
+## Service details
+
+<!-- canonical-documentation -->
+[Service details](https://platform.acedata.cloud/services/018c653e-4f1b-433f-82f9-732ef2767040?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=hcaptcha_mcp_package_quick_start)

mcp_hcaptcha-2026.10.8.0/core/__init__.py

@@ -0,0 +1,15 @@
+"""Core module for MCP HCaptcha server."""
+
+from core.client import HCaptchaClient
+from core.config import settings
+from core.exceptions import HCaptchaAPIError, HCaptchaAuthError, HCaptchaValidationError
+from core.server import mcp
+
+__all__ = [
+    "HCaptchaClient",
+    "settings",
+    "mcp",
+    "HCaptchaAPIError",
+    "HCaptchaAuthError",
+    "HCaptchaValidationError",
+]

mcp_hcaptcha-2026.10.8.0/core/client.py

@@ -0,0 +1,144 @@
+"""HTTP client for HCaptcha API."""
+
+import contextvars
+import json
+from typing import Any
+
+import httpx
+from loguru import logger
+
+from core.config import settings
+from core.exceptions import HCaptchaAPIError, HCaptchaAuthError, HCaptchaError, HCaptchaTimeoutError
+
+_request_api_token: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "_request_api_token", default=None
+)
+
+
+def set_request_api_token(token: str | None) -> None:
+    _request_api_token.set(token)
+
+
+def get_request_api_token() -> str | None:
+    return _request_api_token.get()
+
+
+def _apply_async_flag(payload: dict[str, Any], async_: bool | None) -> None:
+    if async_ is not None:
+        payload["async"] = async_
+
+
+class HCaptchaClient:
+    """Async HTTP client for the AceDataCloud HCaptcha API."""
+
+    def __init__(self, api_token: str | None = None, base_url: str | None = None):
+        self.api_token = api_token if api_token is not None else settings.api_token
+        self.base_url = base_url or settings.api_base_url
+        self.timeout = settings.request_timeout
+        logger.info(f"HCaptchaClient initialized with base_url: {self.base_url}")
+
+    def _get_headers(self) -> dict[str, str]:
+        token = get_request_api_token() or self.api_token
+        if not token:
+            raise HCaptchaAuthError("API token not configured")
+        return {
+            "accept": "application/json",
+            "authorization": "******",
+            "content-type": "application/json",
+        }
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        status = response.status_code
+        try:
+            body = response.json()
+        except Exception:
+            body = {}
+        error_obj = body.get("error", {}) if isinstance(body, dict) else {}
+        code = error_obj.get("code", f"http_{status}")
+        message = (
+            error_obj.get("message")
+            or (body.get("detail") if isinstance(body, dict) else None)
+            or response.text
+            or f"HTTP {status}"
+        )
+        if status in (401, 403):
+            raise HCaptchaAuthError(message)
+        raise HCaptchaAPIError(message=message, code=code, status_code=status)
+
+    async def request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        payload: dict[str, Any] | None = None,
+        timeout: float | None = None,
+        allowed_error_statuses: set[int] | None = None,
+    ) -> dict[str, Any]:
+        method_upper = method.upper()
+        url = f"{self.base_url}{endpoint}"
+        request_timeout = timeout or self.timeout
+        if payload is not None:
+            logger.debug(f"Request payload: {json.dumps(payload, ensure_ascii=False, indent=2)}")
+        async with httpx.AsyncClient() as http_client:
+            try:
+                response = await http_client.request(
+                    method_upper,
+                    url,
+                    json=payload,
+                    headers=self._get_headers(),
+                    timeout=request_timeout,
+                )
+                if response.status_code >= 400 and response.status_code not in (
+                    allowed_error_statuses or set()
+                ):
+                    self._handle_error_response(response)
+                return response.json()  # type: ignore[no-any-return]
+            except httpx.TimeoutException as e:
+                raise HCaptchaTimeoutError(
+                    f"Request to {endpoint} timed out after {request_timeout}s"
+                ) from e
+            except HCaptchaError:
+                raise
+            except Exception as e:
+                raise HCaptchaAPIError(message=str(e)) from e
+
+    async def recognize(
+        self,
+        queries: list[str] | None = None,
+        question: str | None = None,
+        async_: bool | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if queries is not None:
+            payload["queries"] = queries
+        if question is not None:
+            payload["question"] = question
+        _apply_async_flag(payload, async_)
+        return await self.request("POST", "/captcha/recognition/hcaptcha", payload=payload)
+
+    async def get_token(
+        self,
+        website_key: str,
+        website_url: str,
+        rqdata: str | None = None,
+        proxy: str | None = None,
+        async_: bool | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"website_key": website_key, "website_url": website_url}
+        if rqdata is not None:
+            payload["rqdata"] = rqdata
+        if proxy is not None:
+            payload["proxy"] = proxy
+        _apply_async_flag(payload, async_)
+        return await self.request("POST", "/captcha/token/hcaptcha", payload=payload)
+
+    async def get_task(self, task_id: str) -> dict[str, Any]:
+        return await self.request(
+            "POST",
+            "/captcha/tasks",
+            payload={"task_id": task_id},
+            allowed_error_statuses={504},
+        )
+
+
+client = HCaptchaClient()

mcp_hcaptcha-2026.10.8.0/core/config.py

@@ -0,0 +1,53 @@
+"""Configuration management for MCP HCaptcha server."""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+_env_path = Path(__file__).parent.parent / ".env"
+load_dotenv(dotenv_path=_env_path)
+
+
+@dataclass
+class Settings:
+    """Application settings loaded from environment variables."""
+
+    api_base_url: str = field(
+        default_factory=lambda: os.getenv("ACEDATACLOUD_API_BASE_URL", "https://api.acedata.cloud")
+    )
+    api_token: str = field(default_factory=lambda: os.getenv("ACEDATACLOUD_API_TOKEN", ""))
+    request_timeout: float = field(
+        default_factory=lambda: float(os.getenv("HCAPTCHA_REQUEST_TIMEOUT", "120"))
+    )
+    server_name: str = field(default_factory=lambda: os.getenv("MCP_SERVER_NAME", "hcaptcha"))
+    transport: str = field(default_factory=lambda: os.getenv("MCP_TRANSPORT", "stdio"))
+    log_level: str = field(default_factory=lambda: os.getenv("LOG_LEVEL", "INFO"))
+    server_url: str = field(default_factory=lambda: os.getenv("MCP_SERVER_URL", ""))
+    auth_base_url: str = field(
+        default_factory=lambda: os.getenv(
+            "ACEDATACLOUD_AUTH_BASE_URL", "https://auth.acedata.cloud"
+        )
+    )
+    platform_base_url: str = field(
+        default_factory=lambda: os.getenv(
+            "ACEDATACLOUD_PLATFORM_BASE_URL", "https://platform.acedata.cloud"
+        )
+    )
+    oauth_client_id: str = field(
+        default_factory=lambda: os.getenv("ACEDATACLOUD_OAUTH_CLIENT_ID", "")
+    )
+
+    def validate(self) -> None:
+        if not self.api_token:
+            raise ValueError(
+                "ACEDATACLOUD_API_TOKEN environment variable is required. Get your token from https://platform.acedata.cloud"
+            )
+
+    @property
+    def is_configured(self) -> bool:
+        return bool(self.api_token)
+
+
+settings = Settings()

mcp_hcaptcha-2026.10.8.0/core/exceptions.py

@@ -0,0 +1,29 @@
+"""Custom exceptions for MCP HCaptcha server."""
+
+
+class HCaptchaError(Exception):
+    def __init__(self, message: str, code: str = "unknown"):
+        self.message = message
+        self.code = code
+        super().__init__(self.message)
+
+
+class HCaptchaAuthError(HCaptchaError):
+    def __init__(self, message: str = "Authentication failed"):
+        super().__init__(message, code="auth_error")
+
+
+class HCaptchaAPIError(HCaptchaError):
+    def __init__(self, message: str, code: str = "api_error", status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(message, code)
+
+
+class HCaptchaValidationError(HCaptchaError):
+    def __init__(self, message: str):
+        super().__init__(message, code="validation_error")
+
+
+class HCaptchaTimeoutError(HCaptchaError):
+    def __init__(self, message: str = "Request timed out"):
+        super().__init__(message, code="timeout_error")