# signal-found/sf-mcp [Health: Active]

**Category:** 🌐 Social Media  
**Repository:** https://github.com/signal-found/sf-mcp  
**GitHub Stars:** 3  
**npm Downloads (last month):** 112  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/signal-found-sf-mcp

## Description
Connect AI agents to Signal Found's proprietary Reddit outreach network. Find prospects posting about problems your product solves, send personalized DMs at scale via your own Reddit account or a managed bot network of hundreds of accounts, and manage a full outreach CRM — all without leaving your AI client.

## Tools
Capabilities this server exposes over MCP:

- **sf_health** — 
    Preflight check for MCP -> onboard_api connectivity and auth context.

    Use this first in a new session to confirm:
    - backend is reachable
    - current MCP session auth state
    - whether a default client id is configured
    
- **login_with_client_id** — 
    Authenticate MCP session to a Signal Found client account.

    Run this at the start of each session before business tools.
    Most tools require authenticated context and will use this session client id unless
    you pass an explicit `client_id` argument.
    
- **current_client_context** — Return the currently authenticated client context for this MCP server session.
- **agent_quickstart** — 
    Zero-context onboarding playbook for agents using this MCP server.

    Returns the recommended call sequence, common guardrails, and recovery hints.
    
- **logout_client_context** — Clear the active authenticated client context for this MCP server session.
- **list_products** — List all products for a client (slug, display_name, product_unique, folder_id).
- **get_product_tree** — Get nested folders and products for a client, equivalent to frontend product tree.
- **create_new_account** — 
    Create a brand-new Signal Found client account for onboarding.

    Requires:
    - `business_name`
    - `email`

    Returns created `client_id` and (by default) logs this MCP session into it.

    Next step after success:
    - call `create_new_product`
    
- **create_new_product** — 
    Create a product and initialize the agent onboarding session context.

    The response includes:
    - product creation result
    - context packet (existing artifacts + screenshot uri)
    - prompt pack + version metadata

    Prerequisite:
    - authenticated session via `login_with_client_id` (or provide `client_id` explicitly)

    Next step after success:
    - call `run_full_agentic_onboarding` (or run staged tools manually)
    
- **get_onboarding_prompt_pack** — 
    Fetch server-curated prompt contracts that define required onboarding outputs.

    Use this when an agent needs exact formatting/expectations before generating:
    - clarifications
    - conversation transcript
    - market positioning
    - keywords/subreddits

    Use `artifact` for focused contracts:
    - clarifications
    - market_position
    - conversation
    - keywords
    - subreddits
    
- **submit_onboarding_artifacts** — 
    Validate and persist core onboarding artifacts for a product/session.

    Prerequisites:
    - prompt pack must be acknowledged for `session_id`
    - payloads should match the artifact schemas below

    Common use:
    - called by `run_full_agentic_onboarding`
    - can also be used for staged/recovery runs

    Expected formats:
    - market_position: patch object with market position keys
    - conversion_notes: {'Product Name','Payment Terms/Plans','General Notes'}
    - funnels: [{'url','description','primary_use_case', optional 'qualification'}]
    
- **submit_agent_targeting** — 
    Persist targeting artifacts (keywords/subreddits) and return policy/preview.

    Prerequisites:
    - prompt pack must be acknowledged for `session_id`
    - artifacts should already be saved for best results

    Typical next step:
    - approve targeting (done automatically by `run_full_agentic_onboarding` when enabled)

    Formats:
    - keywords: list[str]
    - subreddit_groups: [{'subreddits': ['name1','name2']}]
    
- **onboarding_campaign_decision** — 
    Evaluate readiness and optionally start campaign immediately.

    If not ready and blocked on credits, also returns a checkout link.

    Use this after onboarding reaches targeting approval.
    Set `start_now=true` to attempt campaign launch.
    
- **configure_product_strategy** — 
    Read/update product strategy assets: market position, conversion notes, and funnels.
    
- **configure_targeting** — 
    Read/update subreddit targeting and keywords for a product.
    
- **modify_market_positioning** — 
    Read or update market positioning with explicit format guidance.

    How to use:
    - Call without `market_position_patch` to inspect current data before editing.
    - Send only keys you want to change (patch semantics).

    Expected patch keys (string values):
    - `one_line_pitch`
    - `icp`
    - `competitive_alternatives`
    - `uniqueness`
    - `value_proof`
    - `market_category`
    - `trends`
    - `additional_info`
    
- **modify_conversion_notes** — 
    Read or update conversion notes with explicit required key names.

    How to use:
    - Call without `conversion_notes` to inspect current notes.
    - For updates, provide all three canonical keys for consistency.

    Expected keys (string values):
    - `Product Name`
    - `Payment Terms/Plans`
    - `General Notes`
    
- **modify_funnels** — 
    Read or replace funnels with explicit shape validation.

    How to use:
    - Call without `funnels` to inspect current funnel list.
    - Update is replace-style: provide the full intended funnels list.

    Expected item shape:
    - `url` (string)
    - `description` (string)
    - `primary_use_case` (string)
    - `qualification` (optional string)
    
- **modify_subreddits** — 
    Read or update subreddit targeting groups.

    How to use:
    - Call without `subreddit_groups` to inspect current targeting.
    - Update expects `groups` format used by onboard API targeting endpoint.

    Expected `subreddit_groups` item shape:
    - `subreddits`: list of subreddit names (without `r/` prefix preferred).
    
- **modify_keywords** — 
    Read or update keyword targeting with optional search parameters.

    How to use:
    - Call without `keywords` to inspect current keywords config.
    - Update writes explicit keyword list and optional search params.

    Expected payload shape:
    - `keywords`: list[str]
    - `search_params` (optional):
      - `sort`: one of `relevance|hot|top|new|comments`
      - `time_filter`: one of `hour|day|week|month|year|all`
      - `per_keyword_limit`: int
    
- **list_campaigns** — List campaigns for a client (active/inactive, product mapping, budget, and warning signals).
- **rebalance_resources_to_product** — 
    Shift outbound/day budget from the worst active campaign to a target product campaign.
    
- **portfolio_close_rate** — Compute close rate across all products based on CRM conversion states.
- **compare_confirmed_vs_uninterested** — 
    Pull sample confirmed and uninterested conversations and return side-by-side message snippets.
    
- **crm_workbench** — 
    CRM read/write operations (no reply generation and no DM sending).

    Use `action` to select operation; each action has its own required fields.
    This tool intentionally excludes outbound messaging behaviors.

    Supported actions:
    - list_customers
    - prospect_stats
    - get_conversation_by_id
    - update_conversion_state
    - update_blacklist
    - get_notes
    - update_notes
    
- **list_conversion_states** — Return canonical CRM conversion states available for recategorization.
- **crm_customers_by_state** — List CRM customer data filtered by conversion states with explicit dedupe diagnostics.
- **crm_state_stats** — Return CRM state statistics (unique deduped customer counts by conversion_state).
- **get_deduped_crm_by_category** — Retrieve deduped CRM records by single state or lead-category bucket.
- **get_conversation_by_id** — Get conversation messages for a conversation ID inside a product scope.
- **get_conversation_notes** — Get notes for a CRM conversation in a product scope.
- **update_conversation_notes** — Update notes for a CRM conversation in a product scope.
- **change_crm_state** — Change a customer's CRM conversion state (category) for a product.
- **upsert_conversation_note** — Create/update a conversation note for a product scope conversation.
- **voice_of_customer_report** — 
    Produce a voice-of-customer report combining outcome metrics and confirmed/uninterested conversation samples.
    
- **billing_and_credits** — 
    Get billing + credits overview, and optionally create a checkout session preview/action.
    
- **sales_control_tower** — 
    Command-center summary for a client: products, campaign health, close-rate, and recommendations.

    Best first operational tool after login when the user asks for "what should we do next?"
    
- **get_onboarding_status** — 
    Canonical onboarding progress view for a product/session.

    Returns:
    - current phase
    - next required action
    - prompt-pack ack state
    - targeting approval state
    - missing artifacts + readiness blockers

    Use this for recovery if a previous onboarding run was partial or failed.
    
- **run_full_agentic_onboarding** — 
    Execute the full staged onboarding flow end-to-end in one call.

    Intended for zero-context agents that want a safe default path.
    This tool orchestrates:
    - prompt-pack version + ack
    - clarifications (questions/mode/answers)
    - conversation (mode/transcript/extract)
    - artifact validation + writes
    - targeting submit (+ optional approve)
    - readiness snapshot

    Requirements:
    - `clarifying_questions` must have exactly 3 items
    - pass valid schema payloads for artifacts/targeting

    On partial failure, returns `failed_stage`, `retry_hint`, and completed stages.
    
- **send_reddit_message** — 
    Send Reddit DMs to scraped leads via the Signal Found Chrome extension.

    Three modes (exactly one must be set):
    - target_username: cold DM to a specific Reddit user
    - crm_reply_to: reply to an existing CRM conversation
    - batch_from_working_leads=True: send to all uncontacted working leads for this product

    Message content: provide a manual message, or set generate_message=True (default) to
    auto-generate using the product's market positioning and conversion notes via Phase 2.
    In batch mode, pre-computed suggested_response values are reused when available.

    Requires a Chrome extension connected and active on Reddit. Fails immediately if none
    is online.
    

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "sf-mcp": {
    "command": "uvx",
    "args": ["sf-mcp"],
    "env": {
      "ONBOARD_API_CLIENT_ID": ""
    }
  }
}
```

**Requires environment variables:** `ONBOARD_API_CLIENT_ID` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

# Signal Found MCP

**The only AI tool that connects directly to a proprietary Reddit outreach network — find your prospects, personalize your pitch, and send thousands of DMs per day.**

[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
[![PyPI](https://img.shields.io/pypi/v/sf-mcp)](https://pypi.org/project/sf-mcp/)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-green)](https://python.org)
[![smithery badge](https://smithery.ai/badge/signal-found/reddit-outreach)](https://smithery.ai/servers/signal-found/reddit-outreach)
[![sf-mcp MCP server](https://glama.ai/mcp/servers/signal-found/sf-mcp/badges/score.svg)](https://glama.ai/mcp/servers/signal-found/sf-mcp)

---

## Table of Contents

- [What is Signal Found?](#what-is-signal-found)
- [Two Ways to Operate](#two-ways-to-operate)
- [Quick Setup](#quick-setup)
  - [Claude Desktop](#claude-desktop)
  - [Claude Code (CLI)](#claude-code-cli)
  - [Cursor](#cursor)
  - [VS Code (GitHub Copilot)](#vs-code-github-copilot)
  - [Windsurf](#windsurf)
  - [Cline](#cline-vs-code-extension)
  - [Smithery](#smithery)
- [Local Install (Alternative)](#local-install-alternative)
- [How It Works](#how-it-works)
- [Available Tools](#available-tools)
- [Pricing & Credits](#pricing--credits)
- [Chrome Extension](#chrome-extension)
- [Configuration Reference](#configuration-reference)
- [Support](#support)

[![Signal Found MCP server](https://glama.ai/mcp/servers/signal-found/sf-mcp/badges/card.svg)](https://glama.ai/mcp/servers/signal-found/sf-mcp)

---

## What is Signal Found?

Signal Found is a Reddit-native outreach platform. You describe your product, we find people on Reddit already asking for it, and your AI agent handles the rest — messaging prospects, tracking replies, and optimizing your funnel in real time.

This MCP server gives **Claude, Cursor, VS Code Copilot, Windsurf**, and any other MCP-compatible AI agent direct access to the Signal Found platform. Your agent can:

- **Set up your product** and targeting strategy (subreddits, keywords, positioning)
- **Find prospects** already posting about problems your product solves
- **Send personalized DMs** at scale — hundreds or thousands per day
- **Manage your CRM** — track replies, update conversion states, follow up
- **Analyze performance** — close rates, voice-of-customer reports, campaign health

No custom code. No API wrangling. Just tell your agent what you're selling.

---

## Two Ways to Operate

### DIY — Your Reddit Account
Use the **Signal Found Chrome Extension** to link your own Reddit account. You control the account; Signal Found handles finding and messaging prospects.

**[→ Install the Chrome Extension](https://onboard.signal-found.com/extensions/reddit)**

### Managed Bot Network — Scale to Thousands
Don't want to use your own account? We operate a private network of **hundreds of Reddit accounts** that send outreach on your behalf — fully managed, with volume that a single account simply can't reach.

**Contact [admin@signal-found.com](mailto:admin@signal-found.com) to get onboarded.**

---

## Quick Setup

**Easiest: use our hosted server — nothing to install.**

> **No account yet?** Leave `ONBOARD_API_CLIENT_ID` blank and ask your AI agent to run `create_new_account("Your Company", "you@example.com")` — it will sign you up and authenticate the session automatically.

Get your `client_id` at [signal-found.com](https://signal-found.com), then pick your client below.

---

### Claude Desktop

Edit `claude_desktop_config.json`:
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "signal-found": {
      "url": "https://mcp.signal-found.com/mcp"
    }
  }
}
```

Restart Claude Desktop, then tell it: `Login to Signal Found with client ID: <your-client-id>`

---

### Claude Code (CLI)

```bash
claude mcp add signal-found --transport http https://mcp.signal-found.com/mcp
```

Or add to `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "signal-found": {
      "type": "http",
      "url": "https://mcp.signal-found.com/mcp"
    }
  }
}
```

---

### Cursor

Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):

```json
{
  "mcpServers": {
    "signal-found": {
      "url": "https://mcp.signal-found.com/mcp"
    }
  }
}
```

---

### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "signal-found": {
      "type": "http",
      "url": "https://mcp.signal-found.com/mcp"
    }
  }
}
```

Or add via the VS Code command palette: `MCP: Add Server` → HTTP → paste `https://mcp.signal-found.com/mcp`

---

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "signal-found": {
      "serverUrl": "https://mcp.signal-found.com/mcp"
    }
  }
}
```

---

### Cline (VS Code Extension)

Open Cline settings → MCP Servers → Add Server → paste:

```
https://mcp.signal-found.com/mcp
```

---

### Smithery

One-click install at **[smithery.ai/servers/signal-found/reddit-outreach](https://smithery.ai/servers/signal-found/reddit-outreach)** — Smithery will prompt you for your `client_id` and handle the rest.

---

## Local Install (Alternative)

If you prefer to run the server locally rather than use the hosted deployment:

```bash
pip install sf-mcp
# or: uvx sf-mcp
```

Then use this config in any client above, replacing the `url` approach:

**Claude Desktop:**
```json
{
  "mcpServers": {
    "signal-found": {
      "command": "uvx",
      "args": ["sf-mcp"],
      "env": {
        "ONBOARD_API_CLIENT_ID": "your-client-id-here"
      }
    }
  }
}
```

**Cursor / VS Code / Windsurf:**
```json
{
  "mcpServers": {
    "signal-found": {
      "command": "uvx",
      "args": ["sf-mcp"],
      "env": {
        "ONBOARD_API_CLIENT_ID": "your-client-id-here"
      }
    }
  }
}
```

---

## How It Works

```
You describe your product
        ↓
Signal Found scans Reddit for people posting about
problems your product solves
        ↓
Your agent configures targeting (subreddits, keywords,
market positioning, conversion notes)
        ↓
Messages sent via your Chrome extension or
our managed account network
        ↓
Replies land in your Signal Found CRM
Your agent tracks them, follows up, and closes
```

---

## Available Tools

### Onboarding & Setup
| Tool | Description |
|------|-------------|
| `login_with_client_id` | Authenticate your session, check credit balance |
| `agent_quickstart` | Recommended agent workflow for zero-context onboarding |
| `create_new_account` | Create a new Signal Found client account |
| `create_new_product` | Register a product and start the onboarding flow |
| `get_onboarding_status` | Check onboarding completion for a product |
| `run_full_agentic_onboarding` | Let the agent run the full onboarding pipeline autonomously |

### Targeting & Strategy
| Tool | Description |
|------|-------------|
| `configure_targeting` | Set subreddits and keywords for a product |
| `configure_product_strategy` | Define market positioning and messaging strategy |
| `modify_subreddits` | Add or remove subreddits from targeting |
| `modify_keywords` | Add or remove keywords from targeting |
| `modify_market_positioning` | Update product positioning copy |
| `submit_agent_targeting` | Submit finalized targeting for campaign activation |

### Outreach & Messaging
| Tool | Description |
|------|-------------|
| `send_reddit_message` | Send DMs to prospects (cold, reply, or batch) |
| `onboarding_campaign_decision` | Approve or modify the agent's targeting recommendations |

### CRM & Pipeline
| Tool | Description |
|------|-------------|
| `crm_workbench` | Full CRM view — leads, conversations, states |
| `crm_customers_by_state` | Filter leads by conversion state |
| `crm_state_stats` | Conversion funnel stats |
| `change_crm_state` | Update a lead's conversion state |
| `get_conversation_by_id` | Fetch a specific conversation |
| `get_conversation_notes` | Get notes on a conversation |
| `modify_conversion_notes` | Update conversion/followup notes |
| `upsert_conversation_note` | Add or update a note on a conversation |

### Analytics & Reporting
| Tool | Description |
|------|-------------|
| `sales_control_tower` | Command-center summary: products, campaigns, close rate, recommendations |
| `portfolio_close_rate` | Aggregate close rate across all products |
| `voice_of_customer_report` | Synthesized report from real prospect responses |
| `compare_confirmed_vs_uninterested` | Side-by-side analysis to improve targeting |
| `get_deduped_crm_by_category` | Deduplicated lead list by category |

### Campaigns & Funnels
| Tool | Description |
|------|-------------|
| `list_campaigns` | List all campaigns and their health |
| `list_products` | List all products |
| `get_product_tree` | Full product + campaign hierarchy |
| `rebalance_resources_to_product` | Shift outreach capacity to best-performing product |
| `modify_funnels` | Adjust funnel configuration |

### Billing & Credits
| Tool | Description |
|------|-------------|
| `billing_and_credits` | Credit balance, history, and Stripe checkout URL generation |

---

## Pricing & Credits

Credits are consumed when Signal Found generates and sends outreach messages. One credit ≈ one message.

| Plan | Credits | Price |
|------|---------|-------|
| **Starter** | 1,000 credits | Buy via `billing_and_credits` tool |
| **Pro** | 7,000 credits | Buy via `billing_and_credits` tool |
| **Bot Network** | Unlimited | [admin@signal-found.com](mailto:admin@signal-found.com) |

When you run out of credits, any outreach tool will automatically provide direct Stripe checkout links — no need to leave your AI client.

---

## Chrome Extension

The Signal Found Chrome Extension connects your Reddit account to the platform.

1. **[Install for Chrome](https://onboard.signal-found.com/extensions/reddit)**
2. Open Reddit and make sure you're logged into the account you want to use
3. Ask your agent to run `register_reddit_account(reddit_username)` to register it with Signal Found

Your account is now live — the agent can use it to send DMs.

---

## Configuration Reference

For local installs, copy `.env.example` to `.env`:

```env
# Your client ID from signal-found.com
ONBOARD_API_CLIENT_ID=your-client-id-here

# Request timeout (seconds)
ONBOARD_API_TIMEOUT_SECONDS=60

# Transport: stdio for local, streamable-http for hosted
MCP_TRANSPORT=stdio
```

---

## Support

- **Website:** [signal-found.com](https://signal-found.com)
- **Email:** [admin@signal-found.com](mailto:admin@signal-found.com)
- **Bot network onboarding:** [admin@signal-found.com](mailto:admin@signal-found.com)

---

© 2025 Signal Found. All rights reserved.

<!-- mcp-name: io.github.signal-found/sf-mcp -->