socialscrape-mcp 0.1.0__tar.gz

socialscrape_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Casey Company LLC (SocialScrape)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

socialscrape_mcp-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+# Tests need the repository's ss_* packages and fixtures, so they cannot run from an sdist.
+prune tests

socialscrape_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: socialscrape-mcp
+Version: 0.1.0
+Summary: MCP server for SocialScrape: social media data for Claude, Cursor and other agents
+License-Expression: MIT
+Project-URL: Homepage, https://socialscrape.dev
+Project-URL: Documentation, https://socialscrape.dev/docs
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: http
+Requires-Dist: starlette>=0.40; extra == "http"
+Requires-Dist: uvicorn>=0.30; extra == "http"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: starlette>=0.40; extra == "test"
+Requires-Dist: uvicorn>=0.30; extra == "test"
+Dynamic: license-file
+
+# socialscrape-mcp
+
+The SocialScrape MCP server: social media data (profiles, posts, comments, search, ads,
+transcripts) for Claude, Cursor and any other MCP client that starts a local server.
+
+It is **generated from SocialScrape's endpoint registry** and grouped so an agent sees a usable number of tools instead of one per endpoint:
+
+| Tools | What |
+|---|---|
+| `get_transcript`, `search`, `get_profile`, `get_post`, `get_comments` | The jobs agents do most, across platforms. The platform is an argument. |
+| one per platform (`github`, `facebook`, `twitter`, ...) | `resource` picks the data (`user`, `profile.posts`, ...); parameters follow. |
+| `describe` | Exact parameters, allowed values, price, example arguments. Free, no API call. |
+| `call_endpoint`, `batch`, `get_job`, `monitors`, `get_credits` | Any endpoint by id, up to 100 requests in one call, async jobs, webhooks, balance. |
+
+Only built endpoints appear as tools. A platform shows up in the next release after its endpoints are built.
+
+Every result starts with `ok | credits charged: 1 | credits remaining: 4999` (and the structured
+copy carries the numbers as fields). Failures are free and come back as `isError` with the API's
+error code, a `retryable` flag and what to do next.
+
+## Use it
+
+The server runs on your own machine. Your MCP client (Claude Desktop, Claude Code, Cursor) starts it as a
+subprocess over stdio. SocialScrape does not run a hosted MCP server, so there is no MCP URL to connect to.
+
+```json
+{ "mcpServers": { "socialscrape": {
+    "command": "uvx", "args": ["socialscrape-mcp"],
+    "env": { "SOCIALSCRAPE_API_KEY": "ss_live_..." } } } }
+```
+
+Get a key at <https://socialscrape.dev/app>. Tool discovery works without a key; a tool call without one
+explains how to add it.
+
+**Fewer tools.** Some clients cap the number of tools (Cursor warns past 40). Narrow the list in the `env`
+block:
+
+| | Setting |
+|---|---|
+| only some platforms | `SOCIALSCRAPE_PLATFORMS=github,threads` |
+| only the cross-platform and account tools | `SOCIALSCRAPE_TOOLSETS=core` |
+| only the platform tools | `SOCIALSCRAPE_TOOLSETS=platforms` |
+
+With `core` alone an agent still reaches every endpoint through `describe` and `call_endpoint`.
+
+**Serve it over HTTP yourself.** For a client that can only reach a URL, install the extra and run the
+server on a host you control: `pip install 'socialscrape-mcp[http]'`, then `socialscrape-mcp http --host
+127.0.0.1 --port 8080`. Each request carries its own key in the `x-api-key` header (or
+`Authorization: Bearer ...`), and `?platforms=` and `?toolsets=` narrow the tools. This is yours to run and
+secure; SocialScrape does not offer it as a service.
+
+## Settings (environment)
+
+| Variable | Default | |
+|---|---|---|
+| `SOCIALSCRAPE_API_KEY` | none | stdio only; the HTTP mode reads each request's key |
+| `SOCIALSCRAPE_API_URL` | `https://api.socialscrape.dev` | |
+| `SOCIALSCRAPE_MCP_TRIM` | `1` | ask for `trim=true` (no null fields, no `extra`) unless a call says otherwise; saves context |
+| `SOCIALSCRAPE_MCP_MAX_CHARS` | `100000` | longest answer; longer lists are cut to whole items, transcripts come in windows (`offset`) |
+| `SOCIALSCRAPE_MCP_TIMEOUT` | `70` | seconds to wait for the API |
+| `SOCIALSCRAPE_MCP_ALLOWED_ORIGINS` | any | HTTP mode only; comma list, set it to refuse browser calls from other origins |
+| `SOCIALSCRAPE_PLATFORMS`, `SOCIALSCRAPE_TOOLSETS` | all | see above |
+
+<!-- mcp-name: dev.socialscrape/socialscrape -->

socialscrape_mcp-0.1.0/README.md

@@ -0,0 +1,64 @@
+# socialscrape-mcp
+
+The SocialScrape MCP server: social media data (profiles, posts, comments, search, ads,
+transcripts) for Claude, Cursor and any other MCP client that starts a local server.
+
+It is **generated from SocialScrape's endpoint registry** and grouped so an agent sees a usable number of tools instead of one per endpoint:
+
+| Tools | What |
+|---|---|
+| `get_transcript`, `search`, `get_profile`, `get_post`, `get_comments` | The jobs agents do most, across platforms. The platform is an argument. |
+| one per platform (`github`, `facebook`, `twitter`, ...) | `resource` picks the data (`user`, `profile.posts`, ...); parameters follow. |
+| `describe` | Exact parameters, allowed values, price, example arguments. Free, no API call. |
+| `call_endpoint`, `batch`, `get_job`, `monitors`, `get_credits` | Any endpoint by id, up to 100 requests in one call, async jobs, webhooks, balance. |
+
+Only built endpoints appear as tools. A platform shows up in the next release after its endpoints are built.
+
+Every result starts with `ok | credits charged: 1 | credits remaining: 4999` (and the structured
+copy carries the numbers as fields). Failures are free and come back as `isError` with the API's
+error code, a `retryable` flag and what to do next.
+
+## Use it
+
+The server runs on your own machine. Your MCP client (Claude Desktop, Claude Code, Cursor) starts it as a
+subprocess over stdio. SocialScrape does not run a hosted MCP server, so there is no MCP URL to connect to.
+
+```json
+{ "mcpServers": { "socialscrape": {
+    "command": "uvx", "args": ["socialscrape-mcp"],
+    "env": { "SOCIALSCRAPE_API_KEY": "ss_live_..." } } } }
+```
+
+Get a key at <https://socialscrape.dev/app>. Tool discovery works without a key; a tool call without one
+explains how to add it.
+
+**Fewer tools.** Some clients cap the number of tools (Cursor warns past 40). Narrow the list in the `env`
+block:
+
+| | Setting |
+|---|---|
+| only some platforms | `SOCIALSCRAPE_PLATFORMS=github,threads` |
+| only the cross-platform and account tools | `SOCIALSCRAPE_TOOLSETS=core` |
+| only the platform tools | `SOCIALSCRAPE_TOOLSETS=platforms` |
+
+With `core` alone an agent still reaches every endpoint through `describe` and `call_endpoint`.
+
+**Serve it over HTTP yourself.** For a client that can only reach a URL, install the extra and run the
+server on a host you control: `pip install 'socialscrape-mcp[http]'`, then `socialscrape-mcp http --host
+127.0.0.1 --port 8080`. Each request carries its own key in the `x-api-key` header (or
+`Authorization: Bearer ...`), and `?platforms=` and `?toolsets=` narrow the tools. This is yours to run and
+secure; SocialScrape does not offer it as a service.
+
+## Settings (environment)
+
+| Variable | Default | |
+|---|---|---|
+| `SOCIALSCRAPE_API_KEY` | none | stdio only; the HTTP mode reads each request's key |
+| `SOCIALSCRAPE_API_URL` | `https://api.socialscrape.dev` | |
+| `SOCIALSCRAPE_MCP_TRIM` | `1` | ask for `trim=true` (no null fields, no `extra`) unless a call says otherwise; saves context |
+| `SOCIALSCRAPE_MCP_MAX_CHARS` | `100000` | longest answer; longer lists are cut to whole items, transcripts come in windows (`offset`) |
+| `SOCIALSCRAPE_MCP_TIMEOUT` | `70` | seconds to wait for the API |
+| `SOCIALSCRAPE_MCP_ALLOWED_ORIGINS` | any | HTTP mode only; comma list, set it to refuse browser calls from other origins |
+| `SOCIALSCRAPE_PLATFORMS`, `SOCIALSCRAPE_TOOLSETS` | all | see above |
+
+<!-- mcp-name: dev.socialscrape/socialscrape -->

socialscrape_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "socialscrape-mcp"
+version = "0.1.0"
+description = "MCP server for SocialScrape: social media data for Claude, Cursor and other agents"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+# The hosted (streamable HTTP) server. stdio needs only httpx.
+http = ["starlette>=0.40", "uvicorn>=0.30"]
+test = ["pytest>=8", "starlette>=0.40", "uvicorn>=0.30"]
+
+[project.urls]
+Homepage = "https://socialscrape.dev"
+Documentation = "https://socialscrape.dev/docs"
+
+[project.scripts]
+socialscrape-mcp = "socialscrape_mcp.cli:main"
+
+[tool.setuptools]
+packages = ["socialscrape_mcp"]
+
+[tool.setuptools.package-data]
+socialscrape_mcp = ["catalog.json"]

socialscrape_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

socialscrape_mcp-0.1.0/socialscrape_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""SocialScrape MCP server: public social media data for Claude, ChatGPT, Cursor and other agents."""
+
+__version__ = "0.1.0"

socialscrape_mcp-0.1.0/socialscrape_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())