Skip to main content

hf-mcp

hf-mcp is a standalone MCP server package for the Hack Forums API v2.

Current release line: 0.3.4.

Version 0.3.4 repairs account and b-rating reads through generic POST /api/v2/read and replies through generic POST /api/v2/write, preserving tool names, request fields, and confirm_live=true. Account and b-rating reads were verified with existing authentication. Reply routing was checked offline; no live reply was sent or retried during this repair.

Install

pip install hf-mcp

Entrypoints

  • hf-mcp (aliases hf-mcp serve)
  • python -m hf_mcp
  • hf-mcp setup init
  • hf-mcp auth bootstrap
  • hf-mcp doctor
  • hf-mcp serve

Desktop MCP clients

Desktop client wiring is first-class and documented in docs/client_integration.md, including:

  • direct command launch (hf-mcp serve)
  • module launch (python -m hf_mcp serve)
  • virtualenv/conda launch forms
  • native Windows Python launch
  • Windows desktop client to WSL bridge examples (including Claude Desktop style)

ChatGPT through a private tunnel

For the current ChatGPT Plugins custom MCP flow and an outbound-only OpenAI Secure MCP Tunnel, see docs/chatgpt_tunnel.md. The ChatGPT connection uses full_api by default to expose all 24 currently supported tools. A four-tool read-only profile is documented as an optional restriction. Keep ChatGPT's config separate from other agents' settings; local readiness and end-to-end ChatGPT acceptance are different checks.

Default local paths

  • config: ~/.config/hf_mcp/config.yaml
  • token store: ~/.config/hf_mcp/token.json

Path overrides:

  • HF_MCP_CONFIG for config path
  • HF_MCP_ENV_FILE for explicit .env path
  • HF_MCP_TOKEN_PATH for token path (unless YAML token_path is set)

Full precedence and policy split are documented in docs/configuration.md.

Read output defaults

Read tools default to human-readable content while keeping canonical JSON for scripts.

  • default mode: readable
  • per-call override: output_mode (readable, structured, raw)
  • additive raw payload toggle: include_raw_payload

Compatibility contract for read tools:

  • structuredContent always carries normalized/canonical JSON for automation.
  • output_mode="readable" is the human surface; for thread reads it includes the formatted thread body plus useful thread and first-post fields.
  • output_mode="structured" keeps script-friendly structuredContent with terse text.
  • raw payload remains available as an additive JSON resource when output_mode="raw" or include_raw_payload=true.

See docs/configuration.md for read_output_defaults config and docs/examples.md for concrete request/response examples.

Compounding flow discovery

Use forums.index (alias forums_index) for root discovery when you do not yet have IDs. This tool is backed by maintained package catalog data and can drift from live Hack Forums state between package updates.

Concrete exploration path:

  • forums.index -> forums.read -> threads.read -> posts.read
  • forums.read still requires fid; it is not root discovery.
  • _hf_flow is the machine-readable flow envelope key.
  • _hf_flow.next_actions is the communication layer that lets one tool result feed the next tool call without an agent guessing selectors.
  • _hf_flow currently ships on forums.index, core reads, supported extended reads (bytes.read, contracts.read, disputes.read, bratings.read, sigmarket.market.read, and sigmarket.order.read), local draft/preflight tools, and successful results from existing guarded write helpers after confirmed or stubbed execution.

Automation usage

For automated clients, call read tools with output_mode="structured" when you only need normalized fields, or output_mode="raw" / include_raw_payload=true when you also need the exact upstream HF API payload as an additive MCP resource.

Example:

{
  "tool": "posts.read",
  "arguments": {
    "tid": 6324346,
    "per_page": 1,
    "include_post_body": true,
    "output_mode": "raw",
    "include_raw_payload": true
  }
}

Expected protocol shape:

{
  "content": [
    {"type": "text", "text": "posts.read returned 1 row(s)."},
    {"type": "resource", "resource": {"uri": "hf-mcp://raw/posts.read", "mimeType": "application/json"}}
  ],
  "structuredContent": {
    "posts": [
      {
        "pid": "62946370",
        "tid": "6324346",
        "subject": "The HF API MCP server",
        "message": "[size=xx-large][align=center][css=68]HF MCP Is Live..."
      }
    ]
  }
}

Quick start

pip install hf-mcp
hf-mcp setup init
hf-mcp auth bootstrap
hf-mcp doctor
hf-mcp serve

Before auth bootstrap, create your own Hack Forums API developer app in the HF user control panel. You can use the hosted callback https://cortalabs.github.io/hf_mcp/oauth_callback.html for HF_MCP_EXTERNAL_REDIRECT_URI, or host docs/oauth_callback.html yourself and use that HTTPS URL instead.

Module launch equivalent:

python -m hf_mcp serve

Safety and release posture

  • Read paths and guarded writes are documented publicly, with fail-closed behavior for concrete writes via confirm_live=true.
  • Concrete write helpers currently exposed are threads.create, posts.reply, and Bytes write helpers (bytes.transfer, bytes.deposit, bytes.withdraw, bytes.bump) with repaired argument contracts.
  • scheduled_at on draft artifacts is metadata for operator workflow only; hf-mcp does not ship a scheduler/queue that auto-executes future writes.
  • HF API quote/entity canonicalization on live writes is treated as expected security/sanitization behavior, not a bypass target.
  • Manual live validation in this wave is intentionally narrower: replies only on TID 6083735 plus at most one threads.create in FID 375; no Bytes live writes.
  • contracts.write is not exposed in this release because operator-approved sandbox proof is unavailable.
  • Signature Market write operations and admin-only high-risk write operations are unsupported and unexposed.
  • PM counters (unreadpms, totalpms) are available through me.read when Advanced Info fields are enabled; direct PM content operations are unsupported.
  • Detailed release-boundary and limitation truth is owned by docs/export_boundary.md.

Docs map

Metadata

Release files for hf-mcp 0.3.4

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

Source distribution (sdist)

Source distribution for hf-mcp 0.3.4
File Size Uploaded Provenance Actions
hf_mcp-0.3.4.tar.gz 136.6 kB With provenance Details for hf_mcp-0.3.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hf-mcp 0.3.4
File Interpreter ABI Platform Actions
hf_mcp-0.3.4-py3-none-any.whl Python 3 none any Details for hf_mcp-0.3.4-py3-none-any.whl

Total release size: 239.9 kB

Release files / hf_mcp-0.3.4.tar.gz

Download URL hf_mcp-0.3.4.tar.gz
Size 136.6 kB
Tags Source
SHA-256 checksum
How to use checksums
c552cf4bbaab8fa69fa21a6e1d50cc7da87ad98379a615bc760cfd96bcba951e
BLAKE2b-256 checksum
How to use checksums
b0d78f32d527514d4c10f80320b3afcc37a4c414e8e6f24f1edfa7a135a4ecd3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Release files / hf_mcp-0.3.4-py3-none-any.whl

Download URL hf_mcp-0.3.4-py3-none-any.whl
Size 103.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7aa7db020b95d6732b7775678bd718b4562c646a1fb8a2a7bb39ef57860dcd1e
BLAKE2b-256 checksum
How to use checksums
5b594e7b0de0f0ee7cc0fe1918a11f4b6a283fc9bb9d8c48053eed2d0f49f17c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for hf-mcp 0.3.4

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hf_mcp-0.3.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

0.3.4 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page