### Example CLI Command for Fetching TikTok Profile

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

This command demonstrates how to use a CLI tool to fetch data for a specific TikTok profile. It requires the 'socialcrawl' package to be installed.

```bash
socialcrawl fetch tiktok/profile --handle charlidamelio
```

--------------------------------

### Get Comprehensive Documentation

Source: https://github.com/socialcrawl/mcp/blob/main/docs/GETTING-STARTED.md

Retrieve all available endpoint and parameter information from the agent. Use this when a complete reference is needed.

```python
socialcrawl_get_docs(topic="full")
```

--------------------------------

### Install Socialcrawl MCP Globally

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

Installs the socialcrawl-mcp package globally using npm. Most users can skip this step as npx is recommended for auto-installation.

```bash
npm install -g socialcrawl-mcp
```

--------------------------------

### Unified Response Envelope Example

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

This is an example of the standardized JSON response structure returned by the MCP for any platform or endpoint. It includes success status, platform, endpoint, data, and credit usage.

```json
{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/profile",
  "data": {
    "content": { "text": "...", "media_urls": ["..."] },
    "author": { "username": "charlidamelio", "followers": 156000000 },
    "engagement": { "likes": 5200, "engagement_rate": 0.045 },
    "metadata": { "language": "en", "content_category": "entertainment" }
  },
  "credits_used": 1,
  "credits_remaining": 99
}
```

--------------------------------

### SocialCrawl Request Flow Example

Source: https://github.com/socialcrawl/mcp/blob/main/docs/HOW-IT-WORKS.md

Illustrates the step-by-step process when an agent calls the socialcrawl_request function, from input validation to response formatting.

```text
Agent calls socialcrawl_request({
  platform: "tiktok",
  resource: "profile",
  params: { handle: "charlidamelio" }
})
  |
  |  1. Zod validates input schema
  | 
  |  2. Pre-flight validation (local, no network)
  |     a. Platform "tiktok" exists? → Yes (found in platforms.ts)
  |     b. Resource "profile" exists for tiktok? → Yes (found in endpoints.ts)
  |     c. Required params present? → Yes
  |     d. Each oneOf group satisfied by at least one provided param? → Yes
  |     e. Optional params (if any) forwarded through as-is
  | 
  |  3. Build URL: https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio
  | 
  |  4. HTTP GET with x-api-key header (30s timeout)
  | 
  |  5. Response handling:
  |     - Success (200): unified envelope with data + metadata, truncate if >25K chars
  |     - Error (4xx/5xx): map to actionable error message
  |     - Network failure: return descriptive error
  | 
  |  6. Format response with endpoint context header
  | 
  ← Returns formatted markdown with JSON data
```

--------------------------------

### Retrieve SocialCrawl Documentation

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

Use this tool to get detailed documentation on various SocialCrawl topics. It does not require an API key and returns markdown-formatted documentation. The default topic is 'overview'.

```python
socialcrawl_get_docs(topic="authentication")
```

```python
socialcrawl_get_docs(topic="tiktok")
```

```python
socialcrawl_get_docs()
```

--------------------------------

### MCP Server Configuration for SocialCrawl

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

Configure the MCP server to run the SocialCrawl crawler. This snippet shows the environment variable setup for the 'socialcrawl' service within the 'mcpServers' configuration.

```json
{
  "mcpServers": {
    "socialcrawl": {
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": {
        "SOCIALCRAWL_API_KEY": "sc_xxxxx"
      }
    }
  }
}
```

--------------------------------

### Get Instagram Post Comments

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

Retrieve comments for a given Instagram post URL. Ensure the URL is valid.

```natural-language
Get the comments on this Instagram post: https://instagram.com/p/CwA1234abcd
```

--------------------------------

### General MCP Client Configuration

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

General configuration pattern for any MCP client supporting stdio transport. Ensure the command, arguments, and environment variables are correctly set.

```text
- Command: npx
- Args: ["-y", "socialcrawl-mcp"]
- Environment: SOCIALCRAWL_API_KEY set to your API key
```

--------------------------------

### Discover Endpoints for a Specific Platform

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

Use this tool to find the available endpoints and their required parameters for a given platform. It queries local data and does not require an API key. The platform slug must be a valid string.

```python
socialcrawl_list_endpoints(platform="twitter")
```

--------------------------------

### SocialCrawl MCP Server Architecture Overview

Source: https://github.com/socialcrawl/mcp/blob/main/docs/HOW-IT-WORKS.md

Illustrates the communication flow between an AI agent, the local MCP server, and the SocialCrawl API.

```text
AI Agent (Claude, Cursor, etc.)
    |
    | MCP protocol (stdio)
    |
SocialCrawl MCP Server (local, npx)
    |
    | HTTPS (GET requests)
    |
SocialCrawl API (www.socialcrawl.dev)
    |
    | (upstream)
    |
Data Platforms (42 platforms)
```

--------------------------------

### Configure Claude MCP Client

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

Adds the socialcrawl MCP server to your Claude client using npx and sets the API key environment variable.

```bash
claude mcp add --scope user socialcrawl -- npx -y socialcrawl-mcp
```

```bash
claude mcp add-env socialcrawl SOCIALCRAWL_API_KEY sc_your_key_here
```

--------------------------------

### Explore Available Platforms

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

Ask about the social media platforms accessible through the MCP.

```natural-language
What social media platforms can you access?
```

--------------------------------

### npm Package Bin Entry

Source: https://github.com/socialcrawl/mcp/blob/main/docs/HOW-IT-WORKS.md

Defines the executable command for the npm package, enabling `npx socialcrawl-mcp`.

```json
{
  "bin": {
    "socialcrawl-mcp": "dist/index.js"
  }
}
```

--------------------------------

### MCP Registry Server Configuration

Source: https://github.com/socialcrawl/mcp/blob/main/docs/HOW-IT-WORKS.md

Metadata for the MCP registry, including package details and environment variable requirements.

```json
{
  "name": "io.github.ridiocompany/socialcrawl",
  "packages": [{
    "registryType": "npm",
    "identifier": "socialcrawl-mcp",
    "transport": "stdio"
  }],
  "environmentVariables": [{
    "name": "SOCIALCRAWL_API_KEY",
    "required": true
  }]
}
```

--------------------------------

### Configure Claude Desktop MCP Server

Source: https://github.com/socialcrawl/mcp/blob/main/docs/GETTING-STARTED.md

Add this JSON configuration to your claude_desktop_config.json file to enable the SocialCrawl MCP server for Claude Desktop. Ensure you replace 'sc_your_key_here' with your actual API key.

```json
{
  "mcpServers": {
    "socialcrawl": {
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": {
        "SOCIALCRAWL_API_KEY": "sc_your_key_here"
      }
    }
  }
}
```

--------------------------------

### SocialCrawl MCP Server Project Structure

Source: https://github.com/socialcrawl/mcp/blob/main/docs/HOW-IT-WORKS.md

Details the directory and file organization for the SocialCrawl MCP server project, highlighting key components like the server creation, HTTP client, tools, and data modules.

```text
src/
├── index.ts              # Server creation, tool registration, stdio transport
├── client.ts             # HTTP client for SocialCrawl API calls
├── types.ts              # TypeScript interfaces
├── constants.ts          # Timeouts, character limits, server metadata
├── tools/
│   ├── list-platforms.ts # Formats platform discovery output
│   ├── list-endpoints.ts # Formats endpoint discovery output
│   ├── get-docs.ts       # Retrieves bundled documentation
│   ├── check-balance.ts  # Calls the /v1/credits/balance meta endpoint
│   ├── monitors.ts       # Stateful /v1/monitors/* CRUD (POST/GET/PATCH/DELETE)
│   └── request.ts        # Pre-flight validation + API call execution
├── data/
│   ├── platforms.ts      # 42 platforms with metadata
│   ├── endpoints.ts      # 264 endpoints with full parameter definitions
│   └── docs.ts           # Bundled llms.txt documentation (one topic per platform + fixed topics)
└── schemas/
    └── tools.ts          # Zod input validation schemas for all 6 tools
```

--------------------------------

### Project Structure

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

Illustrates the directory and file organization for the socialcrawl-mcp project, including source code, configuration, and documentation.

```tree
socialcrawl-mcp/
├── src/
│   ├── index.ts              # Entry point — creates MCP server, registers tools
│   ├── client.ts             # SocialCrawl API HTTP client
│   ├── types.ts              # Shared TypeScript types
│   ├── constants.ts          # Base URL, character limits, timeouts
│   ├── tools/
│   │   ├── request.ts        # socialcrawl_request
│   │   ├── list-platforms.ts # socialcrawl_list_platforms
│   │   ├── list-endpoints.ts # socialcrawl_list_endpoints
│   │   └── get-docs.ts       # socialcrawl_get_docs
│   ├── data/
│   │   ├── platforms.ts      # 21 platforms with metadata
│   │   ├── endpoints.ts      # 105 endpoints with params, tiers, descriptions
│   │   └── docs.ts           # Bundled llms.txt documentation content
│   └── schemas/
│       └── tools.ts          # Zod input validation schemas for all 4 tools
├── server.json               # MCP registry metadata
├── package.json              # npm package config with mcpName, bin
├── tsconfig.json
├── README.md                 # Registry-facing documentation
├── LICENSE                   # MIT
└── docs/
    └── specs/                # This file
```

--------------------------------

### List Available SocialCrawl Platforms

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

Use this tool to discover all available platforms supported by SocialCrawl. It queries local data and does not require an API key.

```python
socialcrawl_list_platforms()
```

--------------------------------

### MCP Registry Configuration (server.json)

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

This JSON object defines the metadata for the socialcrawl MCP, including its name, description, repository, package details, and required environment variables.

```json
{
  "name": "io.github.ridiocompany/socialcrawl",
  "description": "Access 21+ social media platforms through one unified API. Get profiles, posts, comments, search results, and analytics from TikTok, Instagram, YouTube, Twitter, LinkedIn, Reddit, and more.",
  "repository": {
    "type": "git",
    "url": "https://github.com/ridiocompany/socialcrawl-mcp"
  },
  "packages": [
    {
      "registryType": "npm",
      "identifier": "socialcrawl-mcp",
      "transport": "stdio"
    }
  ],
  "environmentVariables": [
    {
      "name": "SOCIALCRAWL_API_KEY",
      "description": "Your SocialCrawl API key. Get a free key at socialcrawl.com (100 credits, no credit card required).",
      "required": true
    }
  ]
}
```

--------------------------------

### Compare Follower Counts Across Platforms

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

This query allows for cross-platform comparison of follower counts for a specified user. The MCP makes sequential API calls for each platform.

```natural-language
Compare the follower counts of @mkbhd on TikTok, Instagram, YouTube, and Twitter
```

--------------------------------

### Access Documentation on Credits

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

Query for information regarding the SocialCrawl credit system.

```natural-language
How does the SocialCrawl credit system work?
```

--------------------------------

### Documentation Content Object

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

Represents the structure for bundled documentation content, keyed by topic. Used for storing various documentation sections like overview, authentication, and platform-specific details.

```typescript
const DOCS: Record<string, string> = {
  overview: "...",           // llms.txt content
  full: "...",               // llms-full.txt content
  authentication: "...",     // Extracted section
  credits: "...",            // Extracted section
  errors: "...",             // Extracted section
  tiktok: "...",             // llms-tiktok.txt
  instagram: "...",          // llms-instagram.txt
  // ... all 21 platforms
};
```

--------------------------------

### Configure VS Code (Claude Code) MCP Server

Source: https://github.com/socialcrawl/mcp/blob/main/docs/GETTING-STARTED.md

Add this JSON configuration to your .vscode/mcp.json file or user settings to enable the SocialCrawl MCP server for VS Code with Claude Code. Replace 'sc_your_key_here' with your actual API key.

```json
{
  "servers": {
    "socialcrawl": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": {
        "SOCIALCRAWL_API_KEY": "sc_your_key_here"
      }
    }
  }
}
```

--------------------------------

### Agent Workflow for Requesting TikTok Profile Data

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

Illustrates the sequence of API calls an AI agent makes to retrieve TikTok profile data. It includes steps for listing platforms and endpoints, making the request, and fetching documentation if needed.

```text
Agent: "I need TikTok data for charlidamelio"

1. socialcrawl_list_platforms → sees TikTok has 24 endpoints
2. socialcrawl_list_endpoints(platform: "tiktok") → sees profile needs "handle" param
3. socialcrawl_request(platform: "tiktok", resource: "profile", params: { handle: "charlidamelio" })
   → returns unified profile data with followers, bio, engagement, etc.

If confused at any point:
4. socialcrawl_get_docs(topic: "tiktok") → reads platform-specific documentation
```

--------------------------------

### Platform Interface Definition

Source: https://github.com/socialcrawl/mcp/blob/main/docs/HOW-IT-WORKS.md

Defines the structure for platform metadata. Queried by socialcrawl_list_platforms and used for pre-flight validation.

```typescript
interface Platform {
  slug: string;           // "tiktok"
  name: string;           // "TikTok"
  endpointCount: number;  // 26
  description: string;    // "Profiles, videos, comments, ..."
}
```

--------------------------------

### List TikTok Endpoints

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

Request a list of all available API endpoints for TikTok.

```natural-language
Show me all the TikTok endpoints
```

--------------------------------

### Search YouTube Content

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

Query YouTube for specific content. The MCP will perform a search and return relevant results.

```natural-language
Search YouTube for "machine learning tutorials"
```

--------------------------------

### Endpoint Interface Definition

Source: https://github.com/socialcrawl/mcp/blob/main/docs/HOW-IT-WORKS.md

Defines the structure for every endpoint in the SocialCrawl registry. Includes details on parameters, credit cost, and resource type.

```typescript
interface Endpoint {
  platform: string;         // "tiktok"
  resource: string;         // "profile"
  method: "GET";
  params: ParamDef[];       // [{ name: "handle", required: true, optional: false, description: "...", example: "charlidamelio" }]
  oneOf?: string[][];       // e.g. [["url", "id"]] — at least one of each group must be provided
  creditTier: string;       // "standard" | "advanced" | "premium"
  creditCost: number;       // 1, 5, or 10
  archetype: string;        // "Author", "Post", "PostList", etc.
  summary: string;          // "Get TikTok user profile"
  description: string;      // Longer description
}
```

--------------------------------

### Platform Interface Definition

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

Defines the structure for platform objects, including slug, name, endpoint count, and description. Used in the data layer.

```typescript
interface Platform {
  slug: string;           // "tiktok"
  name: string;           // "TikTok"
  endpointCount: number;  // 24
  description: string;    // "Profiles, videos, comments, followers, search, trending, live streams"
}
```

--------------------------------

### Fetch TikTok Profile

Source: https://github.com/socialcrawl/mcp/blob/main/README.md

Use this query to retrieve a specific TikTok profile. The MCP translates this into a structured API call.

```natural-language
Get the TikTok profile for @charlidamelio
```

--------------------------------

### Unified Response Envelope Structure

Source: https://github.com/socialcrawl/mcp/blob/main/docs/HOW-IT-WORKS.md

Shows the consistent JSON structure returned by successful socialcrawl_request calls, regardless of platform or endpoint.

```json
{
  "success": true,
  "platform": "tiktok",
  "endpoint": "profile",
  "data": { ... },
  "credits_used": 1,
  "credits_remaining": 9847,
  "request_id": "req_...",
  "cached": false
}
```

--------------------------------

### Make a SocialCrawl API Request

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

This is the primary tool for making API calls to SocialCrawl. It requires an API key and handles validation of platform, resource, and parameters before making the HTTP call. It returns the full API response.

```python
socialcrawl_request(platform="twitter", resource="profile", params={"username": "elonmusk"})
```

--------------------------------

### Endpoint Interface Definition

Source: https://github.com/socialcrawl/mcp/blob/main/docs/specs/2026-04-10-socialcrawl-mcp-design.md

Defines the structure for endpoint objects, detailing platform, resource, method, parameters, credit tier, cost, archetype, and summary. Used in the data layer.

```typescript
interface Endpoint {
  platform: string;         // "tiktok"
  resource: string;         // "profile"
  method: "GET";
  params: ParamDef[];       // [{ name: "handle", required: true, description: "...", example: "charlidamelio" }]
  creditTier: string;       // "standard" | "advanced" | "premium"
  creditCost: number;       // 1, 5, or 10
  archetype: string;        // "Author" | "Post" | "PostList" | etc.
  summary: string;          // "Get TikTok user profile"
  description: string;      // Longer description
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.