# Skills & MCP Server (/docs/skills-and-mcp) Skills & MCP Server [#skills--mcp-server] SocialCrawl is available as two standalone packages that give AI agents direct access to the API. Both currently bundle 44 platforms and 357 endpoints of the REST API's 49-platform, 395-endpoint catalogue; they are versioned separately, so the newest platforms land in the packages a release behind. For the complete surface, call the REST API directly. Choose whichever package matches your AI client. Skills Package [#skills-package] The `@socialcrawl` skill works with Claude Code, Cursor, Windsurf, Codex, Gemini CLI, and [40+ other agents](https://skills.sh). It lets your agent fetch current public social media data subject to documented endpoint caches, generate code snippets, and answer API questions through natural language. Install [#install] ```bash # Via skills.sh (recommended) npx skills add socialcrawl/skills # Global (available in all projects) npx skills add socialcrawl/skills -g # Via Git (manual) — the skill lives at skills/socialcrawl in the repo, # and agents discover it at //SKILL.md, so copy that # subdirectory rather than cloning the repo into place. git clone --depth 1 https://github.com/socialcrawl/skills /tmp/socialcrawl-skills mkdir -p .claude/skills cp -r /tmp/socialcrawl-skills/skills/socialcrawl .claude/skills/socialcrawl ``` Set your API key [#set-your-api-key] ```bash export SOCIALCRAWL_API_KEY="sc_your_api_key_here" ``` Add this to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) so it persists across sessions. The skill resolves your key from three sources in order: `$SOCIALCRAWL_API_KEY`, then `~/.config/socialcrawl/api_key`, then a prompt. If it has to prompt, it saves your answer to `~/.config/socialcrawl/api_key` so you only paste it once. The literal placeholder `sc_your_api_key_here` is treated as unset. Use it [#use-it] Invoke the skill directly or just ask in natural language: ``` /socialcrawl ``` ``` Get the TikTok profile for @charlidamelio ``` ``` Search YouTube for "machine learning" videos ``` The skill identifies the platform and endpoint, makes the API call, and returns structured JSON. *** MCP Server [#mcp-server] The `socialcrawl-mcp` server connects any MCP-compatible AI client to the SocialCrawl API. It is published on [npm](https://www.npmjs.com/package/socialcrawl-mcp) and the [MCP Registry](https://registry.modelcontextprotocol.io). Install for Claude Code [#install-for-claude-code] ```bash claude mcp add --scope user socialcrawl -e SOCIALCRAWL_API_KEY=sc_your_key_here -- npx -y socialcrawl-mcp ``` Flags go before the `--` separator; everything after it is the command Claude Code runs. Install for Claude Desktop, Cursor, VS Code, or Windsurf [#install-for-claude-desktop-cursor-vs-code-or-windsurf] Add to your client's MCP config file: ```json { "mcpServers": { "socialcrawl": { "command": "npx", "args": ["-y", "socialcrawl-mcp"], "env": { "SOCIALCRAWL_API_KEY": "sc_your_key_here" } } } } ``` Restart your AI client after saving. Available tools [#available-tools] The MCP server exposes 7 tools: | Tool | Description | Needs API key? | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------- | | `socialcrawl_list_platforms` | Discover every bundled platform with its endpoint count and capabilities | No | | `socialcrawl_list_endpoints` | See all endpoints, required parameters, and credit costs for a platform | No | | `socialcrawl_get_docs` | Access detailed API documentation by topic or platform slug | No | | `socialcrawl_request` | Make any SocialCrawl API call — GET, or POST with a `body` for the [batch endpoints](/docs/batch.md) | Yes | | `socialcrawl_check_balance` | Credit balance and recent deductions via `GET /v1/credits/balance` (0 credits) | Yes | | `socialcrawl_monitors` | Create and manage scheduled [Monitors](/docs/webhooks.md) — create, list, get, runs, timeseries, pause, resume, delete | Yes | | `socialcrawl_web` | Web scraping, search, crawl/batch/agent jobs, change monitors, and browser sessions | Yes | Three of the seven tools work without an API key — they query local bundled data. The four that hit the network (`socialcrawl_request`, `socialcrawl_check_balance`, `socialcrawl_monitors`, `socialcrawl_web`) need a key. Smart validation [#smart-validation] Before making any API call, `socialcrawl_request` validates locally that the platform exists, the endpoint exists, and all required parameters are present. If something is wrong, it tells the agent how to fix it — without consuming any credits. *** Skills vs MCP [#skills-vs-mcp] | | Skills | MCP | | -------------------- | ----------------------------------------------------- | -------------------------------------- | | **Install via** | skills.sh, Git | npm, MCP Registry | | **Protocol** | Skill files read by agent | MCP stdio transport | | **Client support** | Claude Code, Cursor, Windsurf, Codex, Gemini CLI, 40+ | Any MCP-compatible client | | **Discovery tools** | No (skill handles routing) | Yes (3 local-only tools) | | **Local validation** | No | Yes (saves credits) | | **Offline docs** | Yes (reference files) | Yes (bundled data) | | **Monitors** | Yes (reference file, calls the REST API) | Yes (`socialcrawl_monitors` tool) | | **Web/browser** | Yes (reference file, calls the REST API) | Yes (dedicated `socialcrawl_web` tool) | Both packages use the same API, response format, and credit system. Pick whichever your AI client supports.