Skip to main content

hf-mcp

hf-mcp is an MCP server for the Hack Forums API v2. It lets MCP clients such as Claude Desktop, Codex, or ChatGPT read forums, threads, posts, users, and Bytes data, draft and check MyCode locally, and post replies or threads when you explicitly allow it. It is for Hack Forums members who build with MCP clients and want a small, inspectable server that runs under their own API app and never writes without confirmation.

Install

pip install hf-mcp

Requires Python 3.11 or newer.

Quickstart

  1. Create a Hack Forums API v2 developer app in your user control panel. Use https://cortalabs.github.io/hf_mcp/oauth_callback.html as the redirect URL, or host docs/oauth_callback.html yourself.

  2. Put your app credentials in a .env file or your shell:

    HF_MCP_CLIENT_ID=your_app_client_id
    HF_MCP_CLIENT_SECRET=your_app_client_secret
    HF_MCP_EXTERNAL_REDIRECT_URI=https://cortalabs.github.io/hf_mcp/oauth_callback.html
    
  3. Set up, authorize, check, and serve:

    hf-mcp setup init        # writes ~/.config/hf_mcp/config.yaml (profile: reader)
    hf-mcp auth bootstrap    # OAuth flow, saves ~/.config/hf_mcp/token.json
    hf-mcp doctor            # local readiness check, no network calls
    hf-mcp serve             # starts the MCP server on stdio
    
  4. Point your MCP client at the server. For most desktop clients the command is hf-mcp with the argument serve; python -m hf_mcp serve is equivalent. Windows, WSL, and virtualenv launch forms are in docs/client_integration.md.

Other commands: hf-mcp auth status shows token and config state.

Tools

Clients list these tools with underscores instead of dots (for example threads_read for threads.read). These docs and the config file use the dotted names; both refer to the same tool. Full details and selectors are in docs/tool_overview.md.

Read (talk to the Hack Forums API)

  • me.read, users.read
  • forums.index (packaged forum catalog, no IDs needed), forums.read, threads.read, posts.read
  • bytes.read
  • contracts.read, disputes.read, bratings.read
  • sigmarket.market.read, sigmarket.order.read
  • admin.high_risk.read (needs privileged scope)

Draft (local only, nothing is sent to Hack Forums)

  • formatting.preflight checks how MyCode or Markdown converts to Hack Forums MyCode and can save a draft
  • formatting.convert converts Markdown or MyCode to Hack Forums MyCode and reports what could not be carried over; nothing is saved
  • templates.list, templates.render list and fill your own named post templates from templates_dir
  • drafts.list, drafts.read, drafts.update, drafts.delete

Write (live requests, each requires confirm_live=true)

  • threads.create, posts.reply
  • bytes.transfer, bytes.deposit, bytes.withdraw, bytes.bump

Not available: contract writes, Signature Market writes, admin writes, and direct private message content. Private message counters are returned by me.read when advanced account fields are enabled.

Safety model

A profile in your config decides which tools the server registers: reader (18 tools: reads, formatting.convert, the template tools and drafts.list/drafts.read; the default), forum_operator (23 tools: adds formatting.preflight, drafts.update, drafts.delete, threads.create and posts.reply), full_api (all 27 tools), or custom (start empty, opt in per capability and parameter family). Tools outside the profile are not registered at all. Write tools fail closed: without confirm_live=true no request leaves your machine. Drafts are local files, and a draft's scheduled_at is only a note; hf-mcp has no scheduler and never posts on its own. Failures come back as MCP errors with a stable code, such as RATE_LIMITED or WRITE_OUTCOME_UNKNOWN, and never echo tokens or upstream error text. Links and images with unsafe schemes such as javascript: are rejected before anything is posted. Free-text messages and sources are limited to 500,000 characters and anything over that is refused. See docs/security_model.md.

Reading output

Read tools return readable text plus normalized JSON in structuredContent. Pass output_mode as readable (default), structured, or raw, or set include_raw_payload=true to attach the exact upstream response as an extra resource. Results carry an _hf_flow.next_actions hint so a client can chain forums.index → forums.read → threads.read → posts.read without guessing IDs. _hf_flow.server.version reports the running hf-mcp version, which is handy in clients that do not show the MCP handshake. Examples are in docs/examples.md.

Configuration

Config lives at ~/.config/hf_mcp/config.yaml and the token at ~/.config/hf_mcp/token.json. Override them with HF_MCP_CONFIG, HF_MCP_ENV_FILE, and HF_MCP_TOKEN_PATH. Policy goes in YAML and secrets stay in .env or the environment. Your own post templates live in templates_dir (default ~/.config/hf_mcp/templates, setting templates_dir or HF_MCP_TEMPLATES_DIR); the file rules are in docs/configuration.md. See docs/configuration.md and config.example.yaml.

ChatGPT

ChatGPT can connect through an outbound-only private tunnel. Setup, profile choice, and rollback are in docs/chatgpt_tunnel.md.

Documentation

Development

python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check src tests scripts
python -m ruff format --check src tests scripts
python -m mypy

Tests use temporary config, token, and draft paths and block outbound network access. A source checkout reports the version from its pyproject.toml; an installed build reports its distribution metadata version.

License

MIT. See LICENSE.

Metadata

Release files for hf-mcp 0.8.1

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.8.1
File Size Uploaded Provenance Actions
hf_mcp-0.8.1.tar.gz 199.6 kB With provenance Details for hf_mcp-0.8.1.tar.gz

Built distribution (wheel)

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

Total release size: 282.0 kB

Release files / hf_mcp-0.8.1.tar.gz

Download URL hf_mcp-0.8.1.tar.gz
Size 199.6 kB
Tags Source
SHA-256 checksum
How to use checksums
8c838efa246dfdde78b8aac95819a6d72bfadd6f39c9649e4cf513b7f7f3bb10
BLAKE2b-256 checksum
How to use checksums
5a0e150f9aa827af764a6b6bc4f623eb1051cd5220b864ef69c244ce8fe0ce07
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 6, 2026.

Transparency log

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

Download URL hf_mcp-0.8.1-py3-none-any.whl
Size 82.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cbf2edae1a42a81362747ad0a756d96e5b9766a5619b1d8e44907136406681e4
BLAKE2b-256 checksum
How to use checksums
2200586fb62c4d2f6145f3d2e7b9326fb192dc366b422e3786b82c94f25a9a0c
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 6, 2026.

Transparency log

Security for hf-mcp 0.8.1

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.8.1.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 6, 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.8.1 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