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 completedsociallens keyword_search --query "electric vehicles" --platforms x,redditsociallens get_keyword_search --id ks1sociallens get_keyword_search_posts --id ks1sociallens list_user_searchessociallens user_search --query "@someone"sociallens list_expert_searchessociallens expert_search --query "climate science"sociallens get_topic_treesociallens list_agent_runs --status runningsociallens start_agent_run --agent-id ag1 --input "weekly roundup"sociallens create_agent_schedule --agent-id ag1 --cron-expression "0 9 * * *" --name dailysociallens pause_agent_schedule --id s1sociallens list_agent_schedule_runs --id s1sociallens get_integration_setupsociallens update_integration_setup --platform slack --enabled truesociallens 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 installnpm 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.