@hyperstar/mcp

@hyperstar/mcp is the local stdio MCP server for Hyperstar headless workflows. It exposes scoped creator search, campaign roster, bulk email, and inbox tools for MCP clients and authenticates with one service-account API key. It is the same server contract as the hosted connector; only the credential differs. People should use the hosted connector, which acts as the signed-in user. The local package is for automation that runs as a service account, or for clients that cannot use a remote MCP server with OAuth.

This README is self-contained for first-time agent setup. You do not need access to the Hyperstar source repository to install the package, configure an MCP client, or understand the safe workflow order.

Public source and release assets:

https://github.com/Hyperstar-org/hyperstar-mcp
https://github.com/Hyperstar-org/hyperstar-mcp/releases/tag/v0.3.2

Hosted connector

Connect to https://mcp.hyper-star.org/mcp using OAuth. Sign in to your Hyperstar account, select one workspace and approve the displayed permissions. The hosted connector requires no local Node.js installation or API key.

Add to Claude

• Claude: use the prefilled link above, or add the URL in Settings → Connectors.

• ChatGPT: enable developer mode if your account/workspace permits it, create a custom MCP connection with this URL and OAuth, then sign in. Add Hyperstar to a new conversation from its tools menu. See OpenAI's current setup guide.

• Claude Code: run claude mcp add --transport http hyperstar https://mcp.hyper-star.org/mcp, then use /mcp in Claude Code to authenticate.

• Codex: run codex mcp add hyperstar --url https://mcp.hyper-star.org/mcp and complete browser sign-in. Use codex mcp login hyperstar to reconnect.

Start with hyperstar_whoami and get_hyperstar_workflow_guide. The workspace is bound at consent; disconnect in Hyperstar Settings → MCP and reconnect to switch workspaces. Disconnect stops future access, while requests already running and queued emails may finish. The connector can send real emails: review recipients and message content before authorizing a send.

The app's /mcp page is setup guidance. The transport is on the separate mcp.hyper-star.org host.

Related MCP server: Influencers Club MCP Server

Local package requirements

• Node.js 22.12.0 or newer.

• A service-account API key from Team -> API keys. The key is bound to one workspace, so there is no login step and no workspace selection.

• An MCP-capable client that can launch a local stdio server.

Claude Desktop Extension

Claude Desktop users should download and install the production Desktop Extension:

https://app.hyper-star.org/mcp/hyperstar-mcp-0.3.2.mcpb

The extension still runs Hyperstar MCP as a local stdio server; it is not a remote HTTP endpoint.

For local builds from this package source, run npm run build:mcpb and npm run validate:mcpb, then install build/mcpb/hyperstar-mcp-0.3.2.mcpb.

Paste a service-account API key from Team -> API keys into the extension settings as HYPERSTAR_API_KEY. The key is already scoped to one workspace. Claude Desktop users who want to act as themselves should add the hosted connector above instead of the extension.

The npm setup below remains available for Claude Code, Codex-style agents, and other MCP clients that install local stdio servers from a command.

Claude Code Quickstart

For local stdio use, install the npm package and point Claude Code at the hyperstar-mcp binary. For hosted OAuth, use the setup above.

macOS, Linux, and WSL:

claude mcp add hyperstar -- npx -y --package @hyperstar/mcp hyperstar-mcp

Windows PowerShell or Command Prompt:

claude mcp add hyperstar -- npx.cmd -y --package @hyperstar/mcp hyperstar-mcp

Then restart Claude Code or open a new session so the hyperstar_* tools are loaded. If Claude asks for connection details, use:

• package: @hyperstar/mcp

• transport: stdio

• command on macOS/Linux/WSL: npx

• command on Windows: npx.cmd

• args: -y --package @hyperstar/mcp hyperstar-mcp

Set HYPERSTAR_API_KEY in the server's environment; Claude Code's claude mcp add accepts -e HYPERSTAR_API_KEY=... for that.

Install

Run the MCP server directly from npm:

npx -y --package @hyperstar/mcp hyperstar-mcp

The package exposes one binary, hyperstar-mcp, the stdio MCP server. Use the explicit --package @hyperstar/mcp hyperstar-mcp form in MCP client configs so the command stays stable across package versions.

If a client spawns through an environment that loses npm's temporary .bin path, use the equivalent npm exec form:

npm exec --yes --package @hyperstar/mcp -- hyperstar-mcp

Create a service-account key from Team -> API keys in the dashboard. Use the headless workflow preset. Enable inbox write only for agents that are allowed to send inbox replies. The package never asks for a Hyperstar password and has no login command; a person who wants to act as themselves uses the hosted connector.

MCP client config

Configure the service-account API key and use the package's default Hyperstar Product API base URL:

{
  "mcpServers": {
    "hyperstar": {
      "command": "npx",
      "args": ["-y", "--package", "@hyperstar/mcp", "hyperstar-mcp"],
      "env": {
        "HYPERSTAR_API_KEY": "hstar_test_public-prefix.secret"
      }
    }
  }
}

Create API keys in the dashboard from Team -> API keys. Use the headless workflow preset. Enable inbox write only for agents that are allowed to send inbox replies.

Without HYPERSTAR_API_KEY the server still starts so clients can list tools and guides, but every Product API tool fails locally with setup guidance and makes no request. The key fixes the workspace: to work in another workspace, configure a key from that workspace. For a non-production environment, set HYPERSTAR_API_BASE_URL.

Tools

Agents should start by reading get_hyperstar_workflow_guide or the MCP resources/prompts listed below. The MCP server starts without auth so clients can discover tools and guides first; Product API workflow calls still require HYPERSTAR_API_KEY. Tool responses include agent_guidance and, where the next step is deterministic, next_tool and next_arguments.

• hyperstar_whoami

• list_workspaces

• get_hyperstar_workflow_guide

• search_creators

• get_search_results

• list_campaigns

• create_campaign

• save_search_results_to_campaign

• list_campaign_creators

• start_email_unlock

• get_email_unlock_job

• check_bulk_email_readiness

• start_bulk_email

• get_bulk_email_job

• list_inbox_threads

• get_inbox_thread_messages

• get_inbox_aggregates

• update_inbox_thread_state

• send_inbox_reply

Resources and prompts

The server exposes static workflow guides as MCP resources:

• hyperstar://guide/headless-workflow

• hyperstar://guide/search-to-campaign

• hyperstar://guide/bulk-email-safety

• hyperstar://guide/inbox

It also exposes matching prompts:

• hyperstar_headless_workflow

• hyperstar_search_to_campaign

• hyperstar_bulk_email_safety

• hyperstar_inbox_workflow

First Agent Prompts

Use prompts like these with a newly connected agent:

Use the Hyperstar MCP tools. First, discover the available Hyperstar workflow
guides and tell me the safe order for search, campaign save, bulk email, and
inbox handling.

Use Hyperstar to search TikTok creators in the US for ceramic mug reviewers.
Return only a compact summary and explain the next tool I should approve before
saving anything to a campaign.

List my Hyperstar campaigns and explain how you would safely check bulk email
readiness for one campaign without starting a real send.

List recent Hyperstar inbox threads, then read message pages for one thread
and follow continuation to older history before drafting any reply. Do not send
a reply unless I explicitly authorize it.

Workflow Safety

Agents should start with get_hyperstar_workflow_guide or the MCP guide resources. The server exposes these main workflow tools:

• search_creators

• get_search_results

• list_campaigns

• create_campaign

• save_search_results_to_campaign

• list_campaign_creators

• start_email_unlock

• get_email_unlock_job

• check_bulk_email_readiness

• start_bulk_email

• get_bulk_email_job

• list_inbox_threads

• get_inbox_thread_messages

• update_inbox_thread_state

• send_inbox_reply

start_bulk_email and send_inbox_reply perform real sends. Both require send_confirmation: "user_authorized" and a stable idempotency_key. Agents should call readiness and full-thread read tools before asking for send authorization.

Search result tools return compact creator summaries by default. Bulk campaign import uses search_id server-side, so the agent does not need to paste an entire creator list into its context window.

Privacy Policy

Hosted connector: Hyperstar processes the selected workspace's account identity, creator search results, campaign data, email recipients/content and inbox data needed for requested tools. Tool results are shared with the agent provider you connect; that provider's privacy and retention terms also apply. Hyperstar stores the app identity, workspace permissions, grant timestamps and hashed refresh credentials to operate and revoke the connection. A short-lived encrypted token pair supports safe concurrent refresh. Authorization secrets are separate from browser login credentials. Operational request logs support security and reliability. Disconnecting revokes future access but does not delete workspace records, queued work or copies already held by the agent provider. Workspace data follows Hyperstar's privacy and retention policy; requests for access or deletion use the contact below.

Full Hyperstar privacy terms are published at https://app.hyper-star.org/privacy.

Data collection: Hyperstar MCP reads and writes only the Hyperstar account, workspace, campaign, creator-search, bulk-email, and inbox data that the authenticated user or service account can access. Service-account keys are supplied by the user or MCP client configuration; the local package stores no credentials of its own.

Usage and storage: Workflow data is processed by Hyperstar Product API services to perform the requested creator-search, campaign, email, and inbox actions. The local MCP server does not run a separate telemetry service and does not ask for raw Hyperstar passwords in the terminal.

Third-party sharing: The MCP package sends workflow requests to Hyperstar-owned API origins. Email sends, inbox replies, and related delivery events may be processed by Hyperstar's configured infrastructure providers as part of the requested product workflow.

Data retention: Hyperstar account, workspace, campaign, search, email, and inbox records follow Hyperstar's product retention policies. Removing the MCP client configuration removes the only local copy of the API key.

Contact information: For privacy, security, or support questions, contact support@hyper-star.org.

Examples

Search creators:

{
  "tool": "search_creators",
  "arguments": {
    "kind": "semantic",
    "platform": "tiktok",
    "region": "US",
    "query": "ceramic mug reviewers",
    "limit": 25
  }
}

YouTube creator discovery uses keyword retrieval and stable channel IDs:

{
  "tool": "search_creators",
  "arguments": {
    "kind": "keyword",
    "platform": "youtube",
    "region": "US",
    "query": "home coffee equipment reviews",
    "filters": {
      "follower_range": { "min": 1000, "max": 100000 },
      "has_email": true
    },
    "limit": 25
  }
}

Common search filters are supplied as a structured JSON object. Useful fields include follower_range as { "min": 1000, "max": 100000 }, avg_engagement_rate, avg_views, has_email, email_contactability, is_verified, has_tiktok_shop, creator_gender, creator_language, category_1, Instagram category_name, gmv, and gpm; gmv and gpm are TikTok-only. Put broad niches and countries in query / region unless a named structured filter applies. Use sort_by for relevance, follower_count, engagement_rate, avg_views, views_growth_rate, gmv, or gpm.

YouTube supports follower_range, creator_language, and has_email only; reference/product search and metric sorting are unavailable.

Search tools return compact creator summaries by default so agents do not load full profile payloads into context. Use get_search_results with detail_level: "full" only when a page of raw creator rows is explicitly needed. Bulk actions such as save_search_results_to_campaign use search_id server-side and do not require the agent to materialize every creator. The search response includes agent_guidance and next_tools so an unfamiliar agent can continue without knowing the UI flow.

List or create a campaign before saving creators:

{
  "tool": "list_campaigns",
  "arguments": {
    "limit": 25,
    "offset": 0
  }
}

{
  "tool": "create_campaign",
  "arguments": {
    "name": "Summer creator outreach",
    "brand": "Hyperstar",
    "description": "Agent-created campaign for outreach testing"
  }
}

Save search results to a campaign roster:

{
  "tool": "save_search_results_to_campaign",
  "arguments": {
    "campaign_id": 123,
    "search_id": "550e8400-e29b-41d4-a716-446655440000",
    "limit": 100
  }
}

Unlock eligible real catalog addresses before checking readiness. This action requires an explicit cost cap and confirmation; has_business_email is never treated as an address:

{
  "tool": "start_email_unlock",
  "arguments": {
    "campaign_id": 123,
    "recipient_target": {
      "type": "selection",
      "campaign_creator_selection": {
        "workflow_filter": "email_not_sent",
        "platform": "youtube"
      }
    },
    "maximum_chargeable_unlocks": 25,
    "confirm_cost": true,
    "idempotency_key": "campaign-123-youtube-unlock-1"
  }
}

Check recipient readiness before any bulk send:

{
  "tool": "check_bulk_email_readiness",
  "arguments": {
    "campaign_id": 123,
    "recipient_target": {
      "type": "ids",
      "campaign_creator_ids": [7, 8]
    }
  }
}

For filtered campaign roster sends, use recipient_target.type: "selection" and pass campaign_creator_selection. The selection must include at least one narrowing filter such as workflow_filter: "email_not_sent", platform, source_type, search, or has_video; empty selections, workflow_filter: "all" by itself, and exclusions-only selections are rejected.

Start a bulk email job. This performs a real send. The response includes the queued job fields plus next_tool: "get_bulk_email_job" and next_arguments so agents know how to check progress. Only call this after readiness has passed and the user has authorized the send:

{
  "tool": "start_bulk_email",
  "arguments": {
    "campaign_id": 123,
    "subject": "Partnership idea",
    "body_text": "Hi, we would like to introduce our new campaign.",
    "recipient_target": {
      "type": "ids",
      "campaign_creator_ids": [7, 8]
    },
    "idempotency_key": "campaign-123-intro-2026-07-09",
    "send_confirmation": "user_authorized"
  }
}

Read a full inbox thread before replying:

{
  "tool": "get_inbox_thread_messages",
  "arguments": {
    "platform": "youtube",
    "thread_id": 456
  }
}

Reply to an inbox thread. This performs a real send. Only call this after the user has authorized the reply and the agent has reviewed the full message history:

{
  "tool": "send_inbox_reply",
  "arguments": {
    "platform": "tiktok",
    "thread_id": 456,
    "subject": "Re: Partnership idea",
    "body_text": "Thanks for the reply. Here are the next details.",
    "idempotency_key": "thread-456-reply-2026-07-09",
    "send_confirmation": "user_authorized"
  }
}

Clean-Room Smoke Check

Without a repository checkout, verify npm can resolve the package and the binary can start:

npm view @hyperstar/mcp version --silent
npm exec --yes --package @hyperstar/mcp -- hyperstar-mcp --help

These checks do not authenticate and do not call Hyperstar workflow APIs. They prove that npm can resolve the package and the binary can start. The package smoke script also verifies unauthenticated MCP tools/list, resources/list, and prompts/list discovery.

Troubleshooting

• npm error could not determine executable to run: use the explicit --package @hyperstar/mcp -- hyperstar-mcp form.

• Tools answer with "Set HYPERSTAR_API_KEY": the server started without a key. Set HYPERSTAR_API_KEY in the MCP server environment, or use the hosted connector to act as yourself.

• The agent asks how to log in: there is no login. A service-account key is the only local credential, and the hosted connector handles user sign-in.

• Wrong workspace: the key decides the workspace. Create a key in the intended workspace and reconfigure the server.

• Non-production environment: set HYPERSTAR_API_BASE_URL.

Development

npm install
npm test
npm run build
npm run smoke:npm

npm run smoke:npm verifies the published npm package can be resolved and that the binary prints help without requiring local build artifacts, authentication, or real workflow API calls.

Changes in 0.3.2

• Updates MCP runtime dependencies to versions with the published security fixes.

• Inbox message reads request 50 messages by default and accept limit and cursor.

• Follow returned next_arguments to read older pages before relying on complete history.

• Pages are chronological within each newest-first history block. Older API responses without continuation remain readable during rollout.

Changes in 0.3.1

• Email attachment uploads can target one exact platform/thread reply.

• Service-account email uploads use direct PUT and preserve the automation's identity.

• Browser upload handoffs require the initiating human user in the same workspace.

Changes in 0.3.0

The local package now authenticates only with a service-account API key. The hyperstar login CLI, the start_browser_login, complete_browser_login and select_workspace tools, the local auth state file and HYPERSTAR_APP_BASE_URL are gone. User sign-in and workspace switching live in the hosted connector, which exposes the same tools. Existing clients only need HYPERSTAR_API_KEY.

Expanded workflows (0.2.0)

The source includes campaign settings and roster edits, fixed selection copy/removal, windowed performance and revenue, follow-up wave controls, creator lookup, forms, and authenticated file uploads/downloads. CSV/XLSX creator imports support direct uploads and browser handoffs, with durable progress, quota settlement and result CSVs. Workspace usage and capacity checks include bounded unlock estimates without spending credits. Use the task-specific MCP resources for campaign management, reporting, forms/files or imports/usage instead of loading every guide.

Old grants keep their permissions; reconnect or explicitly add the new performance, form and usage:read permissions to an API key when needed. Follow-up email remains dev-only until provider threading verification is complete.