needtofind-mcp

# NeedToFind MCP server

[NeedToFind](https://needtofind.app) is a **reverse marketplace**: instead of searching other people's listings, you post what you're looking for and the people who have it get in touch. This MCP server lets an AI assistant do that for you: post a wanted ad, search open ads, read and answer responses, and set up email alerts.

- **Server URL:** `https://needtofind.app/mcp` (remote, streamable HTTP)
- **Auth:** a personal access token from a free NeedToFind account
- **Cost:** free. No listing fees, no commissions.
- **Also listed on:** the [official MCP Registry](https://registry.modelcontextprotocol.io) (`app.needtofind/needtofind`) and [Smithery](https://smithery.ai)

> This repository holds the documentation and registry metadata for the hosted server. The NeedToFind application itself is not published here.

## Get a token

1. Create a free account at [needtofind.app](https://needtofind.app).
2. Open your profile page and create a token under **API tokens** (shown once; up to 10 per account).
3. Keep it private. Anyone with the token can act as you on NeedToFind. You can revoke it from the same page at any time.

## Connect your client

### Claude Code

```bash
claude mcp add --scope user --transport http needtofind https://needtofind.app/mcp --header "Authorization: Bearer YOUR_TOKEN"
```

### Any client that supports remote HTTP servers with custom headers

```json
{
  "mcpServers": {
    "needtofind": {
      "type": "http",
      "url": "https://needtofind.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

Some gateways reserve the `Authorization` header. The server also accepts the same token as `X-NeedToFind-Token: YOUR_TOKEN`, with or without a `Bearer ` prefix.

### Smithery

Install `info-mw9d/needtofind` from [Smithery](https://smithery.ai/servers/info-mw9d/needtofind) and paste your token when asked.

### Clients that only support OAuth

Not supported yet. Connections use personal access tokens.

## Tools

| Tool | What it does |
|---|---|
| `list_categories` | List the categories and their groups. Use the names exactly as given; the list can change. |
| `search_wants` | Search open wanted ads, optionally by category. Good for checking whether someone already posted a similar want, or finding wants you could fulfil. |
| `whats_new` | List open wanted ads posted since a time (default 24 hours, up to 30 days back), with a `next_since` value to pass back next time. For noticing new demand without re-running a search. |
| `post_want` | Post a wanted ad (title, description, category, optional budget and location). Live for 30 days unless renewed or closed. |
| `my_wants` | List your own ads, any status. |
| `get_responses` | Read the responses sellers sent to one of your ads, including the private message thread with each seller. |
| `close_want` | Close one of your ads, optionally marking the item as found. |
| `respond_to_want` | Respond to someone else's ad to say you have the item. The buyer is emailed your message and contact details. |
| `my_responses` | List the responses you've sent to other people's ads, with message threads and unread counts. |
| `reply_to_response` | Send a private message in a response's conversation (as buyer or seller). The other person is emailed. |
| `set_alert` | Email me when a new ad matches my keywords and/or category (for sellers who want to hear about demand). |
| `list_alerts` | List your saved alerts. |
| `delete_alert` | Delete an alert. |

Every tool declares whether it is read-only, destructive or idempotent, so clients can decide when to ask you first. Tools that email other people (`respond_to_want`, `reply_to_response`) are described to the model as things to do only when you ask.

## Limits

| | |
|---|---|
| Open ads per account | 25 |
| Ad lifetime | 30 days (renewable) |
| Photos per ad | up to 4 (added on the website; MCP tools can't upload files) |
| Responses you can send | 20 per day |
| Alerts per account | 10 |
| MCP requests | 60 per minute per account |
| Tokens per account | 10 |

## Privacy

- Ads are public. Responses and message threads are private between the buyer and that one seller.
- The server only acts as the account that owns the token.
- Details: [Privacy Policy](https://needtofind.app/privacy) and [Terms](https://needtofind.app/terms).

## Example prompts

- "Search NeedToFind for a Marantz 2270 receiver."
- "What new wanted ads were posted in Boats since yesterday?"
- "Post a wanted ad for a Yanmar 3GM30 fuel injector, budget $200, in Key West, FL."
- "Did anyone respond to my injector ad? Summarize the replies."
- "Alert me when someone posts a want for vintage audio gear."

## Support

Use the contact form at [needtofind.app/contact](https://needtofind.app/contact).

NeedToFind is a project of [Gray Penguin Development](https://www.graypenguin.com).