@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 using either a service-account key or local browser CLI login.

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.

Requirements

• Node.js 22.12.0 or newer.
• An active Hyperstar account with access to at least one workspace.
• Either a service-account API key or permission to approve local browser CLI login.
• 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.1.22.mcpb

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

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

If you have a service-account API key from Team -> API keys, paste it into the extension settings as HYPERSTAR_API_KEY. Service-account mode is the simplest Claude Desktop setup because the key is already scoped to one workspace.

If you do not have an API key, ask Claude to use the Hyperstar MCP auth tools:

1. Call start_browser_login.
2. Open the returned authorization URL in your browser.
3. After approving access, have Claude call complete_browser_login.
4. Have Claude call list_workspaces, then select_workspace.

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

Hyperstar MCP is a local stdio MCP server, not a remote HTTP endpoint. Do not look for /mcp, /sse, or a hosted MCP URL on hyperstarai.io or hyper-star.org. Install the npm package and point Claude Code at the hyperstar-mcp binary.

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

For browser login, an agent on the same machine may run:

npx -y --package @hyperstar/mcp hyperstar login --no-open

The agent should show the printed URL to the user, keep the command running, then list workspaces and select exactly one after login completes.

Install And Login

Run the MCP server directly from npm:

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

The package exposes two binaries:

• hyperstar-mcp: the stdio MCP server.
• hyperstar: the local login and workspace helper CLI.

Because the package exposes multiple binaries, use the explicit --package @hyperstar/mcp hyperstar-mcp form instead of bare npx -y @hyperstar/mcp in MCP client configs.

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

For interactive local use, start with browser login. An agent with shell access on the same machine may run this command for the user. The CLI opens Hyperstar in the browser and never asks for a raw Hyperstar password in the terminal:

npx -y --package @hyperstar/mcp hyperstar login
npx -y --package @hyperstar/mcp hyperstar workspaces list --json
npx -y --package @hyperstar/mcp hyperstar workspaces use <organization_id>

If the agent should not open the browser automatically, use --no-open. The agent can show the printed URL to the user and keep the command running while the browser completes the loopback callback:

npx -y --package @hyperstar/mcp hyperstar login --no-open

hyperstar logout revokes and clears the CLI token, but it does not sign out of the browser session at app.hyper-star.org. To switch accounts, sign out in the browser first or open the printed authorization URL in a private browser window. After login, list workspaces and select exactly one before using workflow tools.

For unattended automation, 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.

MCP client config

Service-account auth is the simplest non-interactive setup. For production, configure only 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.

When HYPERSTAR_API_KEY is omitted, the server falls back to the local browser login state created by the hyperstar CLI:

{
  "mcpServers": {
    "hyperstar": {
      "command": "npx",
      "args": ["-y", "--package", "@hyperstar/mcp", "hyperstar-mcp"]
    }
  }
}

Local browser login stores tokens under the OS config directory and the selected workspace in the same auth state file. Run hyperstar login, then either select a workspace with hyperstar workspaces use <organization_id> or use the MCP list_workspaces and select_workspace tools. Service-account mode is already workspace-scoped, so get_hyperstar_workflow_guide omits select_workspace when HYPERSTAR_API_KEY is used. For non-production login, set matching HYPERSTAR_API_BASE_URL and HYPERSTAR_APP_BASE_URL explicitly. HYPERSTAR_API_KEY takes precedence over local CLI auth when both are present.

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 local browser login or HYPERSTAR_API_KEY. Tool responses include agent_guidance and, where the next step is deterministic, next_tool and next_arguments.

• hyperstar_whoami
• start_browser_login
• complete_browser_login
• list_workspaces
• select_workspace
• get_hyperstar_workflow_guide
• search_creators
• get_search_results
• list_campaigns
• create_campaign
• save_search_results_to_campaign
• list_campaign_creators
• 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 the full messages for one thread
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
• 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

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. Browser login stores local CLI auth state on the user's machine; service-account keys are supplied by the user or MCP client configuration.

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. Local CLI auth state remains on the user's machine until the user runs hyperstar logout or removes the MCP client configuration.

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
  }
}

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.

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
  }
}

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": "tiktok",
    "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 both binaries can start:

npm view @hyperstar/mcp version --silent
npm exec --yes --package @hyperstar/mcp -- hyperstar --help
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 both binaries 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 or --package @hyperstar/mcp -- hyperstar-mcp form because the package exposes multiple binaries.
• No Hyperstar auth configured: run hyperstar login and select a workspace, or set HYPERSTAR_API_KEY in the MCP server environment.
• The agent says login must be run manually: the agent can run hyperstar login --no-open, show the printed URL, and wait while the user completes browser authentication on the same machine.
• Login keeps returning the same account: hyperstar logout clears only the CLI token. Sign out of app.hyper-star.org in the browser or use a private window for the authorization URL.
• Workspace errors in browser-login mode: run hyperstar workspaces list --json, then hyperstar workspaces use <organization_id>.
• Non-production login opens the wrong app: set both HYPERSTAR_API_BASE_URL and HYPERSTAR_APP_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 both package binaries print help without requiring local build artifacts, authentication, or real workflow API calls.