Retrieves existing Facehunch reports, account context, and source links for users through a read-only MCP connector.
Also known as facehunch/mcp-server, facehunch-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.2.1
- Last commit
- Nov 9, 2026
- License
- MIT
What is Facehunch MCP?
Facehunch retrieves existing Facehunch reports, account context, and source links for users through a read-only MCP connector.
Summary generated from the project's README
About Facehunch MCP server
Accessing your existing Facehunch reports and account context from within an AI assistant is what this read-only connector enables. It allows users to manage their saved photo-search data by bridging a local stdio client to a hosted server running on Cloudflare. The setup uses browser-based OAuth for authentication, meaning you do not need to manually handle product passwords or deploy workers to use it.
Developers and users can interact with three specific tools: get_profile to read account context, list_reports to view owned reports with their status and metadata, and get_report to retrieve specific metadata and stored source links. The server is designed to respect privacy by hiding locked results and does not perform new searches, identify individuals, or infer sensitive traits. It requires Node.js 22 or newer for local stdio clients and works with clients that support Streamable HTTP MCP and OAuth.
What you can do with it
- 1List saved photo reportsAsk your assistant to show all the reports currently stored in your account including their dates and statuses.
- 2Summarize report source linksRequest a summary of the available source URLs within a specific existing report without identifying any people.
- 3Check report accessibilityVerify if a specific report is accessible or if it is locked, requesting the product link instead of content if it is restricted.
Written from the project's README. Every use case is checked against a quote from it.
How to install Facehunch MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Facehunch MCP in Claude Code
$ claude mcp add mcp-server -- npx -y facehunch-mcpInstall Facehunch MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"facehunch-mcp"
]
}
}
}Install Facehunch MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"facehunch-mcp"
]
}
}
}Install Facehunch MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","facehunch-mcp"]}'Install Facehunch MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"facehunch-mcp"
]
}
}
}Install Facehunch MCP in Codex
$ codex mcp add mcp-server -- npx -y facehunch-mcpInstall Facehunch MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "facehunch-mcp"]
Install Facehunch MCP in Gemini CLI
$ gemini mcp add -s user mcp-server npx -- -y facehunch-mcpInstall Facehunch MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"facehunch-mcp"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablefacehunch/mcp-server is public and reachablegithub.com/facehunch/mcp-server ↗Pass
- Package names this repository as its sourcefacehunch-mcp names facehunch/mcp-server as sourcenpmjs.com/package/facehunch-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for facehunch-mcpnpmjs.com/package/facehunch-mcp/v/1.2.1#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/facehunch/mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from facehunch-mcpPass
- No critical advisory in the package or its dependencies85 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubFacehunch MCP
Photo-search context with clear limits.
Facehunch helps readers understand photo-search methods, source pages and the limits of a visual result. Its guides distinguish finding copies of a photograph from comparing faces across different photographs. The workspace presents a fictional sample and consented API tests; the current FaceCheck test index does not produce reliable identity matches.
Website · MCP repository · Agent skill · npm package
What this connector does
This package connects a local stdio MCP client to the hosted Facehunch MCP server. Hosted tools run on Cloudflare; the local package bridges the connection and opens browser-based OAuth. You do not need to deploy a Worker or paste a product password into your assistant.
| Tool | What it does |
|---|---|
get_profile |
Read the signed-in account context. |
list_reports |
List reports already owned by the account, with status and access metadata. |
get_report |
Retrieve an owned report’s metadata and available stored source links while respecting locked results. |
The MCP does not initiate new face searches, identify people, infer sensitive traits or research personal information. It only retrieves existing owned reports. Locked results remain hidden. An empty report list means the account has no saved reports, not that a photograph has no online matches. Test results are not identity verification.
Example workflow
- Locate a report that already exists in the user’s account.
- Read its status and access state; preserve dates and source URLs exactly as returned.
- Summarize what the stored report contains without inferring identity or treating a similarity score as verification.
Things to ask your assistant
List my saved reports with their dates, statuses and links.
Open this existing report and summarize its available source links without identifying anyone.
Check whether this report is accessible. If it is locked, return its product link instead of guessing its contents.
Connect a remote MCP client
- Open the client’s custom MCP or connector settings.
- Enter
https://mcp.facehunch.com/mcpas the remote server URL. - Complete Facehunch sign-in in your browser and review the permissions on the consent screen.
- Return to the client and load the available tools.
Use a client that supports Streamable HTTP MCP and OAuth. Custom-connector availability depends on the client and your account. A public repository or npm release does not mean the integration has been approved for a client’s marketplace.
Claude Desktop and other stdio clients
Requires Node.js 22 or newer and an existing Facehunch account. Add this entry to your client’s MCP configuration:
{
"mcpServers": {
"facehunch": {
"command": "npx",
"args": [
"-y",
"facehunch-mcp"
]
}
}
}
You can also run npx -y facehunch-mcp from a terminal to start the bridge. It speaks MCP over stdio; it is not an interactive chat interface. For desktop clients that support MCPB extensions, download the .mcpb file from Facehunch releases.
Permissions and account access
Requested scopes: profile:read reports:read. Older profile-only connections need to reconnect and explicitly approve the additional permissions before content tools are available.
Only approve a connection you intended to start. If sign-in opens a new tab, finish it, return to the consent screen and refresh. Manage or revoke connected apps.
The package uses pinned mcp-remote for OAuth, PKCE and local token storage. Tokens on your computer are credentials. The connector uses the fixed endpoint above and rejects command-line endpoint overrides. Product passwords and underlying provider credentials are not requested by this package.
Troubleshooting
- No tools or insufficient permissions: reconnect through browser consent and check the selected account.
- An empty list: confirm that the account owns the expected items. Empty results are different from a failed request.
- A link asks you to sign in: open it with the owning product account; a private product link is not a public share link.
- The browser blocks authorization: inspect the browser’s displayed error and restart an expired request from the client. Never send cookies or tokens in an issue.
Add the companion skill
The Facehunch agent skill explains how to select the right records, interpret results and respect the workflow’s limits:
npx skills add facehunch/agent-skill
Learn more about Facehunch
- Photo search and its limits
- Reverse image search explained
- Face search versus reverse image search
- Photo-search privacy
- Test-mode help centre
- Photo removal
Development and support
npm ci
npm test
npm run bundle
Report a connector issue with your client, Node.js version and a redacted error. Keep package.json, manifest.json, server/config.json, server.json and the lockfile version aligned for releases. GitHub Actions publishes versioned npm packages and MCPB assets. See LICENSE for the MIT license.
Facehunch MCP questions
How do I add Facehunch MCP to Claude Code?
Run claude mcp add mcp-server -- npx -y facehunch-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Facehunch MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can this server perform new face searches?
No, the MCP only retrieves existing reports that the user already owns and does not initiate new searches or identify people.
What happens if my report list is empty?
An empty list indicates that your account does not have any saved reports, rather than suggesting no matches were found for a photograph.
What are the required permissions for this connector?
The connector requests the profile:read and reports:read scopes.