social-listening-mcp
Provides an adapter for ingesting news posts from RSS feeds into the shared post schema for social-listening analysis.
social-listening-mcp
Status: early work, not released.
Tools that let an LLM agent answer social-listening questions ("How was the news sentiment about X last week?") on any data source. All tools talk to one shared post schema, and small adapters connect each data source to that schema. The tools are served over MCP (Model Context Protocol), so any MCP client can use them.
Quickstart (from zero)
Needs Python 3.11+ and git. The GitHub CLI (gh) is optional.
1. Install
git clone https://github.com/arynas/Social-Listening-MCP.git
cd Social-Listening-MCP
python3 -m venv .venv
.venv/bin/pip install -e .2. Download the data snapshot (43,422 Indonesian news headlines, 1–14 Oct 2026; see "Data snapshot" below)
mkdir -p data/snapshot && cd data/snapshot
gh release download data-2026-10-v1 -R arynas/Social-Listening-MCP # or download the files from the release page
shasum -a 256 -c SHA256SUMS && gunzip -k posts-2026-10.labelled.jsonl.gz
cd ../..3. Start the server (stdio; today is frozen at 2026-10-15 in this config, because the snapshot ends on 14 Oct)
.venv/bin/slmcp-server --config config.snapshot.example.yamlIt prints social-listening-mcp 0.0.1 starting (stdio) and waits for an MCP client. Stop it with Ctrl+C.
4. Connect an MCP client. Most clients take a command to start a local server. Give it the full paths:
{"command": ["/path/to/Social-Listening-MCP/.venv/bin/slmcp-server",
"--config", "/path/to/Social-Listening-MCP/config.snapshot.example.yaml"]}For example, in OpenCode put this under mcp in a project opencode.json as {"type": "local", "command": [...]}. Clients that only speak HTTP can use --transport streamable-http (then the URL is http://127.0.0.1:8000/mcp). Use any chat model that supports tool calls; our trial used Qwen3.6-27B (open weights) with thinking off (see docs/client-trial.md).
5. Ask. Example questions:
Bagaimana sentimen berita tentang banjir dari 1 sampai 14 Oktober 2026?
Berapa jumlah berita tentang gempa minggu lalu?
Apa saja sumber berita teratas tentang kesehatan kemarin? Sertakan 3 contoh judul dengan link.
You can also check the tools without a model: .venv/bin/python scripts/proof.py calls them through MCP on the sample data.
Related MCP server: Turbular
Data rules
Fresh code. Everything here is written from scratch. No company code.
Public or synthetic data only. No private or company data, no client names.
No keys or secrets in the repo. Keys go in a local
.envfile, which git ignores.Free models only in examples and demos.
Dependencies
Runtime: PyYAML (only
yaml.safe_load, for the config file) and the official MCP Python SDK (mcp, 2.x) for the server. Everything else uses the Python standard library.Development: pytest, ruff.
Config
Copy config.example.yaml to config.yaml and edit it. See docs/config.md. Keys never go in the file.
Layout
slmcp/: the packageslmcp/adapters/: one adapter per data source (CSV/JSON and RSS news are planned first)slmcp/bench/: benchmark builder, no-model check, model runner and scorerbenchmark/: the benchmark question set (questions-v1.1.jsonl; v1 kept for history) and smoke runstests/: tests (pytest)docs/: documentationexamples/: small sample data (synthetic)
Run the tests
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
.venv/bin/ruff check .MCP server
Two tools, news_recap and social_recap, over stdio (default) or Streamable HTTP. See docs/tools.md.
pip install -e .
slmcp-server --config config.snapshot.example.yamlBenchmark
226 questions (113 in Indonesian, the same in English) on the snapshot, with gold answers computed by code, a no-model check, a runner for any OpenAI-compatible model and an automatic scorer. See docs/benchmark.md. Known failure modes, their fixes and the V&V checklist are in docs/failure-vv.md; each fixed failure has a regression test (docs/regressions.md).
Data snapshot
A ready-made snapshot of 43,422 Indonesian news headlines (1–14 Oct 2026) with sentiment labels is published as a GitHub Release: data-2026-10-v1. See docs/datasheet.md for how it was made and its limits (headlines only; the sentiment labels are rough model output).
mkdir -p data/snapshot && cd data/snapshot
gh release download data-2026-10-v1 -R arynas/Social-Listening-MCP # or download the files from the release page
shasum -a 256 -c SHA256SUMS && gunzip -k posts-2026-10.labelled.jsonl.gzLoad it with a config file (data_source: {adapter: jsonl, path: data/snapshot/posts-2026-10.labelled.jsonl}) or directly:
from slmcp.adapters.csv_json import FileAdapter
adapter = FileAdapter("data/snapshot/posts-2026-10.labelled.jsonl")
print(len(adapter.posts)) # 43422
hits = adapter.search("banjir", "2026-10-01", "2026-10-14")Citation (required when you use or share the data): Data from the GDELT Project, https://www.gdeltproject.org/
Contributing
Work on a branch and open a pull request to
main. Don't push tomaindirectly.CI must be green: lint (ruff), tests (pytest, Python 3.11 and 3.12), package build, proof run, and the security checks (CodeQL, gitleaks, pip-audit).
Every pull request has a Proof section with real output (see the PR template).
Update
CHANGELOG.mdwith each change.The maintainer reviews and merges.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Social media data for agents: profiles, posts, comments, search, ads, transcripts.
Social listening for AI agents: search mentions, pull scored buying signals, score leads
Social media data for AI agents: creators, posts, comments, insights, trending across 6 platforms.
Twitter/X, Instagram, Reddit & TikTok data for AI agents. Billions of posts. No API keys.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables LLM agents to connect to and retrieve data from multiple database types through a unified API, with schema normalization and query transformation for improved compatibility.-
- FlicenseNot gradedqualityAmaintenanceEnables LLM agents to connect to and retrieve data from multiple database types through a unified API, with schema normalization and query transformation for LLM-friendly access.-
- FlicenseNot gradedqualityAmaintenanceEnables LLM agents to connect to and query multiple database types through a unified API, with schema normalization and query transformation.-
- FlicenseNot gradedqualityAmaintenanceEnables LLM agents to connect to and retrieve data from multiple database types through a unified API, with schema normalization and query transformation for easier interaction.-