Sociallens MCP Server

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.