sociallens

sociallens

sociallens talks to Rolli IQ's social-media search and analytics API: keyword, user, and expert searches and the posts they find, the topic tree, agent runs, agent schedules, integration setup, and account usage. One binary serves a command-line interface and a stdio MCP server.

An API token is required. Set ROLLI_API_TOKEN before use; when it is missing or blank, every tool fails with an error before any request is made. ROLLI_USER_ID is optional and defaults to rolli-mcp; its value is sent with every request. The API base URL can be overridden with SOCIALENS_API_URL; when it is not set, calls go to https://api.rolli.ai.

One difference from the original server is worth knowing up front: the original waits, polling until a search completes (which can take up to ten minutes). sociallens makes a single request per tool call and returns whatever status and results the API reports at that moment; call the matching get_* tool again to check on a search that is still running.

Install

npx @reneturcios/sociallens get_usage

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/sociallens

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

The subcommands mirror the MCP tool names:

export ROLLI_API_TOKEN=...

sociallens list_keyword_searches --status completed
sociallens keyword_search --query "electric vehicles" --platforms x,reddit
sociallens get_keyword_search --id ks1
sociallens get_keyword_search_posts --id ks1
sociallens list_user_searches
sociallens user_search --query "@someone"
sociallens list_expert_searches
sociallens expert_search --query "climate science"
sociallens get_topic_tree
sociallens list_agent_runs --status running
sociallens start_agent_run --agent-id ag1 --input "weekly roundup"
sociallens create_agent_schedule --agent-id ag1 --cron-expression "0 9 * * *" --name daily
sociallens pause_agent_schedule --id s1
sociallens list_agent_schedule_runs --id s1
sociallens get_integration_setup
sociallens update_integration_setup --platform slack --enabled true
sociallens get_usage

sociallens --version

Results print the upstream JSON payload. Exit codes: 0 on success, 1 when a call fails (including a missing token or an upstream API error), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/sociallens mcp

MCP client configuration:

{
  "mcpServers": {
    "sociallens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/sociallens", "mcp"],
      "env": { "ROLLI_API_TOKEN": "..." }
    }
  }
}

Tools

Tool	Input	What it does
list_keyword_searches	status (optional)	List keyword searches.
keyword_search	query (required), platforms, start_date, end_date	Start a keyword search.
get_keyword_search	id (required)	Get one keyword search.
list_user_searches	status (optional)	List user searches.
user_search	query (required), platforms, start_date, end_date	Start a user search.
get_user_search	id (required)	Get one user search.
list_expert_searches	status (optional)	List expert searches.
expert_search	query (required), platforms, start_date, end_date	Start an expert search.
get_expert_search	id (required)	Get one expert search.
get_topic_tree	(none)	Get the topic tree.
get_keyword_search_posts	id (required)	Get a keyword search's posts.
get_user_search_posts	id (required)	Get a user search's posts.
list_agent_runs	status (optional)	List agent runs.
start_agent_run	agent_id (required), input	Start an agent run.
get_agent_run	id (required)	Get one agent run.
cancel_agent_run	id (required)	Cancel an agent run.
rerun_agent_run	id (required)	Re-run an agent run.
update_agent_run	id (required), name, status	Update an agent run.
delete_agent_run	id (required)	Delete an agent run.
list_agent_schedules	status (optional)	List agent schedules.
create_agent_schedule	agent_id, cron_expression (both required), name	Create an agent schedule.
get_agent_schedule	id (required)	Get one agent schedule.
update_agent_schedule	id (required), name, cron_expression, agent_id	Update an agent schedule.
delete_agent_schedule	id (required)	Delete an agent schedule.
pause_agent_schedule	id (required)	Pause an agent schedule.
resume_agent_schedule	id (required)	Resume an agent schedule.
list_agent_schedule_runs	id (required), status	List a schedule's runs.
get_integration_setup	(none)	Get the integration setup.
update_integration_setup	platform, webhook_url, enabled	Update the integration setup.
get_usage	(none)	Get account usage.

platforms is an array of platform names. Dates use YYYY-MM-DD form as start_date / end_date.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.