{"id":28185917,"url":"https://github.com/evalstate/hf-mcp-server","last_synced_at":"2025-08-03T06:36:23.866Z","repository":{"id":292242354,"uuid":"978636614","full_name":"evalstate/hf-mcp-server","owner":"evalstate","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-25T07:42:32.000Z","size":797,"stargazers_count":38,"open_issues_count":7,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-25T08:35:40.171Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evalstate.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-06T09:38:37.000Z","updated_at":"2025-06-25T07:42:36.000Z","dependencies_parsed_at":"2025-05-26T20:21:17.699Z","dependency_job_id":"a87977dc-88ff-471e-b59c-77d028a8ecb3","html_url":"https://github.com/evalstate/hf-mcp-server","commit_stats":null,"previous_names":["evalstate/hf-mcp-server"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/evalstate/hf-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evalstate%2Fhf-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evalstate%2Fhf-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evalstate%2Fhf-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evalstate%2Fhf-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evalstate","download_url":"https://codeload.github.com/evalstate/hf-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evalstate%2Fhf-mcp-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261925031,"owners_count":23231325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-16T06:12:51.562Z","updated_at":"2025-08-03T06:36:23.847Z","avatar_url":"https://github.com/evalstate.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hugging Face Official MCP Server \n\n## Getting Started\n\nThis repository contains the offical Hugging Face MCP Server source. The server supports multiple deployment and configuration options, and is deployable locally as well as on your own infrastructure.\n\nThe easiest way to access Hugging Face MCP Services is via `https://hf.co/mcp` which offers a number of Tools, Prompts and access to Gradio Spaces which are configurable at `https://hf.co/settings/mcp`. \n\n![hf_mcp_server_small](https://github.com/user-attachments/assets/d30f9f56-b08c-4dfc-a68f-a164a93db564)\n\nAnonymous access is supported with a default set of Tools and Prompts, or use a Hugging Face READ token to customize your settings:\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall in \u003cb\u003eClaude Desktop\u003c/b\u003e\u003c/summary\u003e\n\u003cbr /\u003e\nFor \u003cb\u003eClaude Desktop\u003c/b\u003e (via MCP Remote) (in your `mcpServers` section):\n\n```JSON\n\"Hugging Face\": {\n    \"command\": \"npx\",\n    \"args\": [\n        \"-y\",\"mcp-remote\",\n        \"https://hf.co/mcp\",\n        \"--header\", \"Authorization:${AUTH_HEADER}\"\n    ],\n    \"env\": {\n    \"AUTH_HEADER\": \"Bearer \u003cYOUR_HF_TOKEN\u003e\"\n    }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eInstall in \u003cb\u003eVSCode\u003c/b\u003e or \u003cb\u003eCursor\u003c/b\u003e\u003c/summary\u003e\n\u003cbr /\u003e\nFor \u003cb\u003eVSCode\u003c/b\u003e and \u003cb\u003eCursor\u003c/b\u003e (in your `mcp/servers`or `mcpServers` section respectively):\n\nIf you prefer to use OAuth, use `https://hf.co/mcp?login`\n\n```JSON\n\"hf-mcp-server\": {\n    \"url\": \"https://hf.co/mcp\",\n    \"headers\": {\n        \"Authorization\": \"Bearer \u003cYOUR_HF_TOKEN\u003e\"\n    }\n```\n\u003c/details\u003e\n\nFor **claude.ai**  enter `https://hf.co/mcp` from the \"Add Integrations\" dropdown menu. Claude does not currently support the MCP 2025-06-18 OAuth standard so is limited to anonymous access.\n\n## Quick Guide (Repository Packages)\n\nThis repo contains:\n\n - (`/mcp`) MCP Implementations of Hub API and Search endpoints for integration with MCP Servers. \n - (`/app`) An MCP Server and Web Application for deploying endpoints.\n\n### MCP Server\n\nThe following transports are supported:\n\n- STDIO \n- SSE (To be deprecated, but still commonly deployed).\n- StreamableHTTP\n- StreamableHTTP in Stateless JSON Mode (**StreamableHTTPJson**)\n\nThe Web Application and HTTP Transports start by default on Port 3000. \n\nSSE and StreamableHTTP services are available at `/sse` and `/mcp` respectively. Although though not strictly enforced by the specification this is common convention.\n\n\u003e [!TIP]\n\u003e The Web Application allows you to switch tools on and off. For STDIO, SSE and StreamableHTTP this will send a ToolListChangedNotification to the MCP Client. In StreamableHTTPJSON mode the tool will not be listed when the client next requests the tool lists.\n\n### Running Locally\n\nYou can run the MCP Server locally with either `npx` or `docker`. \n\n```bash\nnpx @llmindset/hf-mcp-server       # Start in STDIO mode\nnpx @llmindset/hf-mcp-server-http  # Start in Streamable HTTP mode\nnpx @llmindset/hf-mcp-server-json  # Start in Streamable HTTP (JSON RPC) mode\n```\n\nTo run with docker: \n\n```bash\ndocker pull ghcr.io/evalstate/hf-mcp-server:latest\ndocker run --rm -p 3000:3000 ghcr.io/evalstate/hf-mcp-server:latest\n```\n![image](https://github.com/user-attachments/assets/2fc0ef58-2c7a-4fae-82b5-e6442bfcbd99)\n\nAll commands above start the Management Web interface on http://localhost:3000/. The Streamable HTTP server is accessible on  http://localhost:3000/mcp. See [Environment Variables](#Environment Variables) for configuration options. Docker defaults to Streamable HTTP (JSON RPC) mode.\n\n\n## Development\n\nThis project uses `pnpm` for build and development. Corepack is used to ensure everyone uses the same pnpm version (10.12.3).\n\n```bash\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n```\n\n### Build Commands\n\n`pnpm run clean` -\u003e clean build artifacts\n\n`pnpm run build` -\u003e build packages\n\n`pnpm run start` -\u003e start the mcp server application\n\n`pnpm run buildrun` -\u003e clean, build and start\n\n`pnpm run dev` -\u003e concurrently watch `mcp` and start dev server with HMR\n\n\n## Docker Build\n\nBuild the image:\n```bash\ndocker build -t hf-mcp-server .\n```\n\nRun with default settings (Streaming HTTP JSON Mode), Dashboard on Port 3000:\n```bash\ndocker run --rm -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server\n```\n\nRun STDIO MCP Server:\n```bash\ndocker run -i --rm -e TRANSPORT=stdio -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server\n```\n\n`TRANSPORT` can be `stdio`, `sse`, `streamingHttp` or `streamingHttpJson` (default).\n\n### Transport Endpoints\n\nThe different transport types use the following endpoints:\n- SSE: `/sse` (with message endpoint at `/message`)\n- Streamable HTTP: `/mcp` (regular or JSON mode)\n- STDIO: Uses stdin/stdout directly, no HTTP endpoint\n\n### Stateful Connection Management\n\nThe `sse` and `streamingHttp` transports are both _stateful_ - they maintain a connection with the MCP Client through an SSE connection. When using these transports, the following configuration options take effect:\n\n| Environment Variable              | Default | Description |\n|-----------------------------------|---------|-------------|\n| `MCP_CLIENT_HEARTBEAT_INTERVAL`   | 30000ms | How often to check SSE connection health |\n| `MCP_CLIENT_CONNECTION_CHECK`     | 90000ms | How often to check for stale sessions |\n| `MCP_CLIENT_CONNECTION_TIMEOUT`   | 300000ms | Remove sessions inactive for this duration |\n| `MCP_PING_ENABLED`                | true    | Enable ping keep-alive for sessions |\n| `MCP_PING_INTERVAL`               | 30000ms | Interval between ping cycles | \n\n\n### Environment Variables\n\nThe server respects the following environment variables:\n- `TRANSPORT`: The transport type to use (stdio, sse, streamableHttp, or streamableHttpJson)\n- `DEFAULT_HF_TOKEN`: ⚠️ Requests are serviced with the HF_TOKEN received in the Authorization: Bearer header. The DEFAULT_HF_TOKEN is used if no header was sent. Only set this in Development / Test environments or for local STDIO Deployments. ⚠️\n- If running with `stdio` transport, `HF_TOKEN` is used if `DEFAULT_HF_TOKEN` is not set.\n- `HF_API_TIMEOUT`: Timeout for Hugging Face API requests in milliseconds (default: 12500ms / 12.5 seconds)\n- `USER_CONFIG_API`: URL to use for User settings (defaults to Local front-end)\n- `MCP_STRICT_COMPLIANCE`: set to True for GET 405 rejects in JSON Mode (default serves a welcome page).\n- `AUTHENTICATE_TOOL`: whether to include an `Authenticate` tool to issue an OAuth challenge when called\n- `SEARCH_ENABLES_FETCH`: When set to `true`, automatically enables the `hf_doc_fetch` tool whenever `hf_doc_search` is enabled\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevalstate%2Fhf-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevalstate%2Fhf-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevalstate%2Fhf-mcp-server/lists"}