---

"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

---

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.

Package	What it does	Reference
`@socialgo/mcp`	The socialgo-mcp SMM MCP server — lets Claude and other AI assistants search the catalog and place orders for you.	MCP docs
`@socialgo/cli`	The socialgo command — browse services, place and track orders, manage your wallet, all from the terminal.	CLI docs
`@socialgo/sdk`	TypeScript client for the social media marketing API — typed models, a fetch-based client, and pricing/markup helpers.	SDK docs

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

Tool	What it does
socialgo_services	Search/filter the catalog by natural-language intent (query, optional platform/type, limit). Returns only the relevant services with id, rate per 1,000, min/max and refill/cancel/dripfeed flags. The search-then-act entry point.
socialgo_service_details	Full details for one service by id (rate, min, max, type, refill/cancel/dripfeed). Confirm limits before ordering.
socialgo_place_order	Create an order for a service id against a link. Supports quantity, drip-feed (runs + interval), and per-type params (comments, usernames, hashtags, hashtag, username, media, answer_number). Charged to your wallet.
socialgo_order_status	Status of one order (order) or many at once (orders list): status, charge, start_count, remains, currency.
socialgo_refill	Request a refill for one (order) or many (orders) orders, when the service supports it. Returns refill id(s).
socialgo_refill_status	Status of a refill (Pending/Completed/Rejected) by refill id or order id.
socialgo_cancel	Cancel one or more orders by id (when the service allows it).
socialgo_orders	List the account's order history (id, charge, status, start_count, remains, link, quantity, created_at).
socialgo_balance	Current account balance (balance + currency). Use before ordering to confirm funds.
socialgo_wallet	Richer than socialgo_balance: balance + currency plus the most recent ledger transactions (deposits, charges) so the assistant can explain recent activity.
socialgo_add_funds	Create a pending wallet top-up for an amount via a method, and return the payment to finish in the panel. Balance lands only after the payment confirms.
socialgo_mass_order	Place several orders in one call from a list of { service, link, quantity }. Each line is independent — one failure doesn't cancel the rest.
socialgo_create_subscription	Set up a recurring subscription: re-order a service every interval minutes for a total number of runs. An ongoing schedule, distinct from a single drip-feed order.
socialgo_subscriptions	List the user's recurring subscriptions with status, remaining runs, interval and next run.
socialgo_validate_coupon	Preview a coupon code without redeeming it: validity, kind (deposit bonus / wallet credit), value, minimum and expiry. Read-only.
socialgo_affiliate_stats	The user's own referral link and affiliate numbers (code, balance, commission rates, referral counts, total earned). Scoped to the API key.
socialgo_loyalty_status	The user's loyalty tier, points, lifetime spend and progress toward the next tier.
socialgo_recommend	Recommend related services from an anchor service id and/or a platform — a ranked list with a reason (bought together, same platform, popular). The natural cross-sell.
socialgo_build_campaign	Build a campaign plan from a budget, a goal and a delivery window in days. Returns a reviewable plan (quantity, cost, schedule) — it does not place any order.
socialgo_storefront	Resolve a public storefront by slug and return the store with its offered packages (title, quantity, reference price).

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)

Tool	What it does
socialgo_guest_gateways	List the payment gateways currently active on the panel. Returns { gateway, label, kind, coins, notice } — gateway is the value to pass as method. Not a fixed list.
socialgo_guest_order	Create a pay-per-order with just an email, a serviceId, a link, and a quantity. Returns { orderId, guestToken, url, amount, currency }. The order ships only after payment confirms.
socialgo_guest_order_status	Track a guest order by id, proving ownership with the token (preferred) or the email used. Returns safe order fields only.

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.

Command	What it does
socialgo config	Show the resolved API URL and whether a key is set.
socialgo balance	Show your wallet balance.
socialgo services list	List the full catalog.
socialgo services search <query>	Search services by name, category, type, or id.
socialgo service <id>	Show one service's details (rate, min/max, refill/cancel/dripfeed).
socialgo order add --service <id> --link <url> [--quantity n]	Place an order. Supports --runs/--interval (drip-feed) and per-type params (--comments, --usernames, --hashtags, --hashtag, --username, --media, --answer-number); list params accept a file path or inline text.
socialgo order status <ids...>	Status of one or many orders (batch).
socialgo order refill <id>	Request a refill for an order.
socialgo order cancel <ids...>	Cancel one or more orders.
socialgo refill-status --refill <id> / --order <id>	Status of a refill.
socialgo orders	List your order history.
socialgo mass-order --line "<s|l|q>" / --file <csv>	Place several orders in one call from inline lines or a `service
socialgo wallet	Balance plus recent transactions.
socialgo add-funds --amount <v> --method <gateway>	Create a pending top-up payment (finish it in the panel).
socialgo subscription create --service <id> --link <url> --quantity <n> --runs <n> --interval <min>	Set up a recurring subscription: N runs every X minutes.
socialgo subscription list	List your recurring subscriptions.
socialgo coupon validate <code>	Preview a coupon (validity, kind, value, expiry) without redeeming it.
socialgo affiliate stats	Your affiliate numbers (referral code/link, balance, commissions, referrals).
socialgo affiliate link	Print just your referral link and code.
socialgo loyalty	Your loyalty tier, points and progress to the next tier.
socialgo recommend <serviceId|platform>	Recommended services from an anchor service and/or a platform.
socialgo campaign build --budget <v> --days <n> [--platform p | --service id] [--goal g]	Build a campaign plan (quantity, cost, schedule) — does not place an order.
socialgo storefront <slug>	Resolve a public storefront by slug and list its packages.
socialgo guest-gateways	List the panel's active payment gateways.
socialgo guest-services [--platform p] [--q term]	Browse the public catalog (no key) to find a serviceId.
socialgo guest-order <serviceId> --email <e> --link <url> [--quantity n] [--method g]	Create a no-account order; returns a payment URL.
socialgo guest-status <id> --token <t> / --email <e>	Track a guest order.

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 [email protected] \
  --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 [email protected] \
  --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.

Variable	Required	What it is
SOCIALGO_API_URL	Yes	Base URL of your SocialGO panel, e.g. https://api.usesocialgo.com. The SMM v2 endpoint is {SOCIALGO_API_URL}/api/v2.
SOCIALGO_API_KEY	No — optional	Buying never needs it. Only for account/tracking mode (order history, wallet, refills, subscriptions). Your API key lives in the panel under Account › API. Leave it unset to buy as a guest.

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.

	MCP (@socialgo/mcp)	CLI (@socialgo/cli)	SDK (@socialgo/sdk)
You are…	running an AI assistant (Claude, etc.)	an operator or scripter in a terminal	a developer building an app/integration
Interface	natural-language tools over MCP	socialgo command (human or --json)	TypeScript functions and types
Best for	conversational "find and order X for me"	one-off ops, cron jobs, shell pipelines	embedding ordering/pricing in your own code
Catalog access	socialgo_services search-then-act	services search, service <id>	full services() list, you filter
Guest checkout	socialgo_guest_* tools	guest-services / guest-order / guest-status	build on the public endpoints
Pricing helpers	—	—	applyMarkup, orderCost, resolveMarkup

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