MCP server, CLI and agent skills

The official insightsocial npm package is a CLI and a stdio MCP server in one, and the agent skill teaches your agent how to use it. All three are open source under the InsightSocial GitHub organization. You do not need any of them to use the API, which is plain HTTPS (see Using an AI agent), but they save your agent from writing its own HTTP client and keep large responses out of its context.

One command

npx -y insightsocial init

init asks for your key, checks it and saves it to ~/.insightsocial/config.json, installs the agent skill into the agents it finds, and writes or prints the MCP config. Get a key at insightsocial.app/portal/api/keys. New accounts include 10 free calls.

MCP server

The server runs locally over stdio and reads the key that insightsocial login (or init) saved, so your MCP config holds no secret.

claude mcp add insightsocial --scope user -- npx -y insightsocial mcp

{
  "mcpServers": {
    "insightsocial": { "command": "npx", "args": ["-y", "insightsocial", "mcp"] }
  }
}

You can pass INSIGHTSOCIAL_API_KEY in the server's env instead of saving it. Without a key, searching and describing endpoints still work. The server is listed in the official MCP Registry as app.insightsocial/insightsocial.

Because every result is saved in full and re-read with read_result, a 50 KB page of comments never has to sit in the model's context, and reading it again costs nothing.

Agent skill

The skill teaches an agent the workflow: search, price, call, page. It also covers when a call is free and when to stop and ask before spending. It uses the MCP server when it is connected and falls back to the CLI or plain REST when it is not.

npx skills add insightsocial/skills

claude plugin marketplace add insightsocial/skills
claude plugin install insightsocial@insightsocial

gemini extensions install https://github.com/insightsocial/skills

CLI

The same package works from a terminal or a script. Results are saved under ./.insightsocial/, so you can reshape them later without paying again.

npx -y insightsocial search instagram followers
npx -y insightsocial describe /v1/instagram/profile
npx -y insightsocial run /v1/instagram/profile -p handle=natgeo
npx -y insightsocial view --last --jq '.data.author | {username, followers}'
npx -y insightsocial credits

search, list, describe, view and credits are free. run costs the endpoint's price and prints the exact command for the next page when there is one. Each page is a separate charged call.

OpenAPI spec

To generate a client or your own agent tools, use the OpenAPI 3.1 spec. It is live and keyless at https://api.insightsocial.app/v1/openapi.json, and a copy synced daily from the live API is at github.com/insightsocial/openapi.

Next steps