Metadata-Version: 2.4
Name: social-search-mcp
Version: 0.1.2
Summary: A Model Context Protocol (MCP) server for deep social media search (SearXNG, Serper, Google).
Project-URL: Homepage, https://github.com/shubhamekapure/social-search-mcp
Project-URL: Issues, https://github.com/shubhamekapure/social-search-mcp/issues
Author-email: Shubham <author@example.com>
Keywords: ai,claude,llm,mcp,search,social-media
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests
Description-Content-Type: text/markdown

# Social Search MCP Server

<!-- mcp-name: io.github.shubhamekapure/social-search-mcp -->
A Model Context Protocol (MCP) server that empowers LLMs to search across specific social media platforms using the industry's best search engines.

## Overview
This server provides a `search_social` tool that accepts a query and an optional list of platforms (facebook, reddit, linkedin, etc.). It filters results exclusively to those domains and returns them directly to the LLM context.

## Search Providers

You can configure the backend by setting the `SEARCH_PROVIDER` environment variable. By default, it uses **SearXNG** since it is free and open-source.

### 1. SearXNG (Default)
SearXNG is a free, open-source internet metasearch engine.
- `SEARCH_PROVIDER=searxng`
- `SEARXNG_URL=http://localhost:8080` (Defaults to localhost, specify a remote public instance if you don't host your own, but note that public instances often limit automated JSON requests).

### 2. Serper.dev
A powerful Google Search wrapper API. Highly recommended for accurate results.
- `SEARCH_PROVIDER=serper`
- `SERPER_API_KEY=your_key` (Get one from [Serper.dev](https://serper.dev/))

### 3. Google Custom Search
The official Google Custom Search API.
- `SEARCH_PROVIDER=google`
- `GOOGLE_API_KEY=your_key`
- `GOOGLE_CX=your_cx_engine_id`

## Setup
Ensure you have Python 3.10+ installed.

```bash
# Clone or place in a directory, then:
python -m venv venv
source venv/bin/activate
pip install -e .
```

## Usage with Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "social-search-mcp": {
      "command": "/ABSOLUTE/PATH/TO/venv/bin/social-search-mcp",
      "args": [],
      "env": {
        "SEARCH_PROVIDER": "searxng",
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}
```
Replace `/ABSOLUTE/PATH/TO/` with the actual path to this folder. Restart Claude Desktop after updating the config.
