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
-
Create a Hack Forums API v2 developer app in your user control panel. Use
https://cortalabs.github.io/hf_mcp/oauth_callback.htmlas the redirect URL, or hostdocs/oauth_callback.htmlyourself. -
Put your app credentials in a
.envfile 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
-
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
-
Point your MCP client at the server. For most desktop clients the command is
hf-mcpwith the argumentserve;python -m hf_mcp serveis equivalent. Windows, WSL, and virtualenv launch forms are indocs/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.readforums.index(packaged forum catalog, no IDs needed),forums.read,threads.read,posts.readbytes.readcontracts.read,disputes.read,bratings.readsigmarket.market.read,sigmarket.order.readadmin.high_risk.read(needs privileged scope)
Draft (local only, nothing is sent to Hack Forums)
formatting.preflightchecks how MyCode or Markdown converts to Hack Forums MyCode and can save a draftdrafts.list,drafts.read,drafts.update,drafts.delete
Write (live requests, each requires confirm_live=true)
threads.create,posts.replybytes.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 (reads
and local drafts, the default), forum_operator (adds threads.create and
posts.reply), full_api (all 24 tools), or custom (start empty, opt in per
capability). 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. 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.
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. 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
- Configuration
- Auth bootstrap
- Client integration
- ChatGPT tunnel
- Tool overview
- Coverage matrix
- Examples
- Security model
- Changelog
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.6.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hf_mcp-0.6.2.tar.gz | 175.1 kB | With provenance | Details for hf_mcp-0.6.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hf_mcp-0.6.2-py3-none-any.whl | Python 3 | none | any | Details for hf_mcp-0.6.2-py3-none-any.whl |
Total release size: 282.0 kB
Release files / hf_mcp-0.6.2.tar.gz
| Download URL | hf_mcp-0.6.2.tar.gz |
|---|---|
| Size | 175.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8ba1ee8bb71bd66d5e20ddce080e03e6e729e638333746ac2ebdc79b132c1299
|
|
BLAKE2b-256 checksum How to use checksums |
17d098b99a610bd038bb87b6b5254c854c68e6b9f8848beb77251790b554850c
|
| 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 logRelease files / hf_mcp-0.6.2-py3-none-any.whl
| Download URL | hf_mcp-0.6.2-py3-none-any.whl |
|---|---|
| Size | 106.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
548831d7ee7eb43850f287e79cb054d7ed074bc7c98c032ec11a262b010af8a6
|
|
BLAKE2b-256 checksum How to use checksums |
a8b3c23a3d14874f43b64c99baec61be9af01db7828debadffcbab8e2ae803b5
|
| 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 logSecurity for hf-mcp 0.6.2
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.
Attestation for hf_mcp-0.6.2.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 logA 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.