SocialGO Tools

Tell Claude what you want. It runs your SMM panel.

The first MCP server + CLI for a Social Media Marketing (SMM) platform — the AI-native way to run social media marketing.

Browse the catalog, place and track orders, and manage your balance straight from Claude (and Cursor, Cline, Windsurf, VS Code), from your terminal, or from your own code. No clicking around a legacy PHP panel.

"Find me 1,000 Instagram followers for instagram.com/mypage and place the order."

Claude finds the right service, checks the price, places the order, and hands you the order ID. That sentence is the whole workflow.

Table of contents

• The old way vs. the AI-native way

• The mechanism: three tools, one typed toolkit

• Use it from Claude (30-second setup)

• The SMM MCP server tools

• The SMM CLI commands

• Quickstart — MCP (AI assistants)

• Quickstart — CLI (terminal)

• Quickstart — SDK (your code)

• Guest checkout: buy with no account

• Installation

• Configuration

• Which one should I use?

• Who it's for

• Documentation

• Contributing

• Security

• License

Related MCP server: Meta Marketing API MCP Server

The old way vs. the AI-native way

An SMM panel exposes thousands of services and a verbose, form-encoded HTTP protocol behind a click-heavy PHP dashboard. To order followers you log in, hunt through menus, copy a service ID, paste a link, set a quantity, submit, then keep refreshing a status page. Automating it means hand-wiring key + action form bodies and parsing raw JSON yourself.

SocialGO Tools removes that friction. The same typed core speaks the standard SMM API v2 protocol (POST {SOCIALGO_API_URL}/api/v2) and gives you three ways to drive your panel:

• Talk to it. Add the MCP server to Claude and order in plain English — no account, no API key needed to buy. No service IDs to memorize, no forms.

• Script it. The socialgo CLI buys as a guest (no key) and, optionally, runs the full reseller flow from your terminal or a cron job.

• Build on it. The TypeScript SDK ships typed models plus dependency-free pricing/markup helpers for resellers.

Buying is guest-first. Anyone can browse and buy with no account and no API key (pay-per-order; an email is just a receipt/tracking contact, not a signup). An account + API key is optional — add it only for better tracking (order history, wallet, refills, subscriptions).

MCP (the Model Context Protocol) is the new standard that lets AI assistants call real tools. Legacy SMM panels are PHP click-UIs with no AI surface at all. As far as we know, this is the first MCP server and CLI built for an SMM platform.

The mechanism: three tools, one typed toolkit

Everything is one core wearing three faces. Pick the surface that fits how you want to work; the behavior is identical underneath.

The clever part is the MCP server's search-then-act design. A panel can carry thousands of services. Registering one tool per service would blow up the model's context. Instead the server exposes a small, fixed set of tools, anchored by socialgo_services: the assistant searches by intent ("cheap Instagram followers"), gets back only the relevant services with IDs and prices, then acts on the one it picked. The tool count stays constant no matter how big the catalog gets.

Beyond find-and-order, the assistant can now plan and grow: socialgo_recommend proposes the natural next service from an anchor or platform, socialgo_build_campaign turns a budget and a delivery window into a reviewable plan before anything is charged, socialgo_storefront reads a public store's packages by slug, and socialgo_add_funds starts a wallet top-up. And the whole conversation works in any language — ask in English, Portuguese or Spanish and the assistant narrates the data back in the language you used.

Use it from Claude (30-second setup)

This is the part that changes how you work. Add the SMM MCP server once, then just ask. No API key is required — buying is guest-first.

Claude Desktop — add this to your claude_desktop_config.json and restart Claude. Only the panel URL is needed:

{
  "mcpServers": {
    "socialgo": {
      "command": "npx",
      "args": ["-y", "@socialgo/mcp"],
      "env": {
        "SOCIALGO_API_URL": "https://api.usesocialgo.com"
      }
    }
  }
}

Claude Code — one command, no key:

claude mcp add socialgo \
  --env SOCIALGO_API_URL=https://api.usesocialgo.com \
  -- npx -y @socialgo/mcp

The same npx -y @socialgo/mcp command works in Cursor, Cline, Windsurf, and VS Code — point each client's MCP config at it with SOCIALGO_API_URL.

Now ask in natural language:

"Find cheap Instagram followers and order 1,000 for instagram.com/mypage."

Here's what happens under the hood — the default, keyless path is guest checkout:

1. Claude calls socialgo_guest_services with your intent and gets back the matching services (IDs, rates per 1,000, min/max). No account, no key.

2. It calls socialgo_guest_order with the service ID, your link, the quantity, and a contact email — and hands you back a payment URL plus a tracking token.

3. You pay at the link; the order ships only after payment confirms. Claude tracks it with socialgo_guest_order_status (by token or email).

Optional — only for ongoing tracking. If you already have a SocialGO account and want order history, a wallet, refills, or subscriptions, add your API key as a second env var (SOCIALGO_API_KEY=YOUR_API_KEY) alongside SOCIALGO_API_URL. That unlocks the reseller tools (socialgo_services, socialgo_place_order, socialgo_order_status, …). Buying never requires it — without a key, Claude just uses the guest tools above.

Building from source instead of npm? Swap npx -y @socialgo/mcp for node /absolute/path/to/socialgo-tools/packages/mcp/dist/index.js. See Installation.

The SMM MCP server tools

A small, fixed toolset — the complete list the server registers, straight from the code. Account-mode tools use your API key; guest tools need no account.

Account mode

Works in any language. Ask in English, Portuguese, Spanish or anything else — the assistant reads the figures back to you in the language you used.

Guest mode (no account, no API key)

See the full MCP reference for every parameter.

The SMM CLI commands

The socialgo command covers the whole reseller flow. Add --json to any command for script-friendly raw output. Global flags --api-url and --key override the environment per command.

Full flag-by-flag detail in the CLI reference, or run socialgo <command> --help.

Quickstart — MCP (AI assistants)

See Use it from Claude above for the copy-paste config. Once connected, ask Claude things like:

"What's my SocialGO balance?"

"Order 5,000 YouTube views for this video: youtube.com/watch?v=..."

"Check the status of order 98765, and refill it if it's done."

Quickstart — CLI (terminal)

Buying is guest-first — no account and no API key. Only the panel URL is needed:

npm i -g @socialgo/cli

export SOCIALGO_API_URL="https://api.usesocialgo.com"   # no key needed to buy

# guest checkout: find a service, order it, track it — no account
socialgo guest-services --platform instagram --q "followers"
socialgo guest-order <serviceId-uuid> \
  --email you@example.com \
  --link https://instagram.com/yourpage \
  --quantity 1000
socialgo guest-status <ORDER_ID> --token <GUEST_TOKEN>

The email is only a contact for the receipt and tracking — it is not a signup and creates no account. See Guest checkout.

Optional — reseller mode (account + API key). If you have an account and want order history, a wallet, refills and subscriptions, set SOCIALGO_API_KEY too and the full reseller flow opens up:

export SOCIALGO_API_KEY="YOUR_API_KEY"   # optional — only for account/tracking
socialgo balance                              # check your wallet
socialgo services search "instagram followers"
socialgo order add --service 1234 --link https://instagram.com/yourpage --quantity 1000
socialgo order status 98765
socialgo order add --service 70 --link <url> --runs 10 --interval 30        # drip-feed
socialgo order add --service 55 --link <url> --comments ./comments.txt      # custom comments

Building from source? The same commands run via node packages/cli/dist/index.js <command>.

Quickstart — SDK (your code)

npm i @socialgo/sdk

import { SmmV2Client, applyMarkup, orderCost } from "@socialgo/sdk";

const client = new SmmV2Client({
  apiUrl: `${process.env.SOCIALGO_API_URL}/api/v2`, // the SMM v2 endpoint
  apiKey: process.env.SOCIALGO_API_KEY!,
});

// catalog + orders
const services = await client.services();
const { order } = await client.add({ service: 1234, link: "https://...", quantity: 1000 });
const status = await client.status(order);

// reseller pricing helpers (dependency-free)
const sellRate = applyMarkup(0.9, { multiplier: 1.5 }); // supplier rate per 1,000 → sell rate
const cost = orderCost(sellRate, 1000);                 // cost for a 1,000-unit order

The client also exposes multiStatus, refill, cancel and balance, plus the newer wallet, addFunds, massOrder, subscriptionCreate, subscriptions, couponValidate, affiliateStats, loyaltyStatus, recommend, campaignBuild and storefront methods; the SDK exports resolveMarkup for cascading category overrides. See the full SDK reference.

Guest checkout: buy with no account

This is the main way to buy: no account, no API key, no wallet. Guest mode is pay-per-order and you pay once at checkout. The email is only a contact for the receipt and tracking — it is not a signup and creates no account.

# 1. List the active payment gateways (use a name as --method)
socialgo guest-gateways

# 2. Browse the public catalog and grab a service id (a UUID, in the ID column)
socialgo guest-services --platform instagram --q "followers"

# 3. Create the order — returns a payment URL. <serviceId> is the UUID from step 2.
socialgo guest-order <serviceId-uuid> \
  --email you@example.com \
  --link https://instagram.com/yourpage \
  --quantity 1000 \
  --method mercadopago

# 4. Track it with the token you received (or the email you used)
socialgo guest-status <ORDER_ID> --token <GUEST_TOKEN>

The order ships for delivery only after payment confirms. Payment methods are never hardcoded — they come live from your panel (/gateways/active). Full walkthrough in the guest checkout guide.

Installation

The npm packages publish under the @socialgo org. The primary path:

npm i -g @socialgo/cli     # the `socialgo` command
npx -y @socialgo/mcp       # the MCP server (point your AI client at this)
npm i @socialgo/sdk        # the TypeScript SDK

Or build from source (a pnpm monorepo):

git clone https://github.com/SocialGOcompany/socialgo-tools.git
cd socialgo-tools
pnpm install
pnpm build      # builds @socialgo/sdk, @socialgo/cli and @socialgo/mcp

After pnpm build, the CLI lives at packages/cli/dist/index.js and the MCP server at packages/mcp/dist/index.js. Run cd packages/cli && npm link to get the global socialgo command from a source build.

Configuration

Every tool reads the same two environment variables. Secrets always come from the environment — nothing is hardcoded, and no upstream supplier is ever exposed.

To buy, you only ever need the panel URL:

export SOCIALGO_API_URL="https://api.usesocialgo.com"   # all you need to buy (guest)

Add the key only if you want account/tracking mode — it is never required to place an order:

export SOCIALGO_API_KEY="YOUR_API_KEY"   # optional — account mode only, not for buying

The CLI also accepts --api-url and --key to override per command.

Which one should I use?

All three speak the same SMM API v2 protocol against the same panel. Pick by how you want to drive it.

The CLI and MCP server are both built on top of the SDK. Want maximum control? Drop down to the SDK. Want batteries included? Use the CLI or MCP.

Who it's for

• SMM resellers who want to run a panel from one chat window, a terminal, or a cron job instead of clicking through a dashboard. Markup helpers handle reseller pricing in code.

• Developers embedding social-media-marketing ordering into their own apps with a typed client.

• Anyone buying a single order — guest checkout means no account required.

Documentation

• Getting started — install, API key, env setup, your first order, guest mode.

• MCP reference — the socialgo-mcp SMM MCP server and every tool.

• CLI reference — every socialgo command and flag.

• SDK reference — the @socialgo/sdk client, types, and pricing helpers.

• API reference — the SMM API v2 protocol and guest endpoints these tools speak.

• Guest checkout guide — buying without an account, end to end.

• Troubleshooting — common errors and fixes.

• FAQ — quick answers.

See also the ROADMAP.

Contributing

Contributions are welcome. This is a pnpm monorepo.

git clone https://github.com/SocialGOcompany/socialgo-tools.git
cd socialgo-tools
pnpm install
pnpm build      # build all packages
pnpm typecheck  # type-check all packages
pnpm test       # run tests

Open an issue to discuss substantial changes before sending a pull request, and read CONTRIBUTING.md first.

Security

Found a vulnerability? Follow our security policy — please don't open a public issue for sensitive reports.

License

MIT © SocialGO