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

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.