@orchyn/mcp

MCP (Model Context Protocol) server for orchyn.

Gives an AI assistant three things: it can read real social posts across ten networks (TikTok, Instagram, YouTube, X/Twitter, Reddit, LinkedIn, Douyin, Xiaohongshu, Weibo, Bilibili), understand them — transcript, hook, script structure, comment themes, why one post beat another — and make something from what it learned: hooks, variants to film, a scored draft, a repurposed thread.

It also monitors a name: search_mentions sweeps nine of those networks for every comment that says your brand, inside a date window you choose.

Runs over stdio locally or as a hosted connector at https://mcp.orchyn.com/mcp. Billed against your orchyn credits; new accounts get 20 free.

Install (one link)

Claude Code — register the marketplace, then install the plugin:

/plugin marketplace add orchynX/mcp
/plugin install orchyn@orchyn

Claude Code / CLI without the plugin:

claude mcp add orchyn --user -- npx -y @orchyn/mcp
npx @orchyn/mcp login   # one-time sign-in (Google)

Cursor / any stdio MCP client (claude_desktop_config.json, .mcp.json, …):

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

Tools

28 tools, grouped by what you are trying to do. Prices are in orchyn credits and match what the server actually charges.

Read a post

Understand a post

Research a niche or a creator

Make something

Account

How billing works

• New accounts get 20 free credits.
• The AI analysis tools (analyze_post, understand_social_post, analyze_creator_profile, analyze_comments, compare_posts, and the text-only tools) are free the first time you use each one. Data tools bill from the first call.
• A call that fails is refunded automatically, and a call interrupted mid-flight is billed once at most — retries are idempotent.
• Platform admins bypass credit debiting entirely.
• check_orchyn_credits lists which free first uses you still have.

Interactive cards in Claude / ChatGPT chat

Every tool that returns posts also renders inline interactive cards directly in the chat (MCP Apps ui://orchyn/view resource rendered in a sandboxed iframe):

• Video posts (TikTok/IG/YouTube/Douyin/LinkedIn) — an inline <video> player with the thumbnail as poster, playing the re-hosted permanent MP4 (no expiring CDN tokens).
• Carousels / slideshows — a horizontally scrollable strip of every slide with an image count chip.
• Single images — inline thumbnail.
• Text-only posts (LinkedIn / X) — a styled quote block of the post text.
• Official brand marks — each card shows the platform's real logo (simple-icons) in its brand color instead of an emoji.

search_mentions renders a different view, because monitoring is triage rather than browsing:

• The comment leads. Its text is the first thing in the row, with the term highlighted everywhere it appears and a ×N badge when one comment names the brand more than once. Who wrote it and when sits underneath.
• Each post carries its reach. The same sentence under a 25K-upvote thread and under a post nobody saw are not the same problem, and nothing else on screen tells you which one you are reading.
• The per-network counts are filters. Click one to narrow to it; a network that answered with nothing is shown but is not clickable, because filtering to it is a dead end. Filtering and sorting redraw from what you already paid for — the view never re-queries.
• A burst collapses. One post with a run of near-identical replies (a coordinated fan campaign, say) shows the first few and offers the rest, so it cannot push four other networks off the screen.
• Comments are selectable, and the selection is agentic. Tick any comments, or select a whole thread at once, and send them — the view hands the host the comment ids the tool issued, so the model can reply to, escalate or analyse exactly those. Selections survive filtering and sorting.
• Load more pages from the nextOffset the tool returned.

Also inline thumbnails render for the model / plain-text clients:

• get_social_media / understand_social_post / analyze_post — up to 4 frames inline (poster + carousel slides). The full mediaItems[].preview_url + thumbnailUrl stay in structuredContent for the model to reason over.
• discover_social_posts / get_user_posts / analyze_creator_profile — each returned post shows its thumbnail inline (up to 4 at once) together with its title/caption + views/likes/comments. Say "next" or "show more" — Claude will re-call with offset/limit pagination. Say "analyze the 2nd one" — Claude calls analyze_post or understand_social_post on that URL.
• Batch analysis — ask "analyze all 4" or "understand these 3 in batch" and Claude will call analyze_post/understand_social_post once per URL in parallel and summarize. For large batches, discover_social_posts + a follow-up analyze_post per URL is the recommended flow.

The backend's analyze_post now watches the actual video/images (direct MP4, YouTube fileUri, or 6 carousel frames via AI multimodal) — not just the caption. The analysis includes a whatHappens field describing exactly what is seen.

Prerequisites

• Node.js >= 18 (tested on Node 22)
• An orchyn account (created automatically on first sign-in — Google sign-in via npx @orchyn/mcp login; the dashboard is not required: the server auto-creates a default workspace + app for new accounts)
• Access to an orchyn server — defaults to the cloud API (https://api.orchyn.com); point ORCHYN_BASE_URL at your own deployment for local development

Quick start

# 1. Sign in with your orchyn account (Google sign-in opens in your browser)
npx @orchyn/mcp login
#    or with email/password:
npx @orchyn/mcp login --email you@example.com --password '...'

# 2. Add it to your MCP client (see install section above) — or run it manually:
npx @orchyn/mcp            # stdio (default; for Claude Desktop / Cursor)
npx @orchyn/mcp --http     # remote HTTP with OAuth (for OpenAI Agents SDK)

login stores your orchyn tokens in ~/.config/orchyn-mcp/credentials.json (mode 0600). If your browser cannot be opened automatically, copy the URL it prints into a browser manually.

Usage in Claude Desktop

After npx @orchyn/mcp login, add to claude_desktop_config.json:

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

Tokens are resolved from the credentials file written by login (or from ORCHYN_ACCESS_TOKEN). If your client does not inherit your shell environment, set the env vars explicitly:

{
  "mcpServers": {
    "orchyn": {
      "command": "npx",
      "args": ["-y", "@orchyn/mcp"],
      "env": {
        "ORCHYN_BASE_URL": "http://localhost:8080"
      }
    }
  }
}

Usage in Cursor

In .mcp.json (project root) or ~/.cursor/mcp.json:

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

After adding the server, run npx @orchyn/mcp login in your terminal — Cursor spawns the server with your environment, so it picks up the stored credentials.

For remote/HTTP usage, Cursor can connect to the OAuth-enabled HTTP mode with npx @orchyn/mcp --http running, pointing the server URL at http://localhost:3457/mcp. Remote clients (including Cursor) discover the OAuth endpoints from http://localhost:3457/.well-known/oauth-authorization-server, open the "Sign in with Google" page, and store the resulting access token.

Usage with OpenAI Agents SDK

Start the HTTP transport:

npx @orchyn/mcp --http --port 3457

Python:

from agents import Agent, Runner
from agents.mcp import RemoteMCPClient

async def main():
    async with RemoteMCPClient(
        url="http://localhost:3457/mcp",
        auth_provider="oidc",  # OAuth flow opens your browser once
    ) as client:
        agent = Agent(name="orchyn", mcp_servers=[client])
        result = await Runner.run(
            agent,
            "Analyze this video: https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        )
        print(result.final_output)

TypeScript (Agents SDK):

import { Agent } from "agents";
import { RemoteMCPClient } from "agents/mcp/client";

const client = new RemoteMCPClient({
  url: "http://localhost:3457/mcp",
  authProvider: "oidc", // opens the browser for the OAuth flow
});

const agent = new Agent({
  name: "orchyn",
  mcpServers: [client],
});

const result = await agent.run(
  "Analyze this video: https://vm.tiktok.com/abc123/",
);
console.log(result.output);

For a local stdio process with the Agents SDK, use StdioMCPClient (Python: StdioMCPClient(command="npx", args=["@orchyn/mcp"])).

Command line

orchyn-mcp                    Start in stdio mode (default transport)
orchyn-mcp --stdio            Same as above
orchyn-mcp --http [--port N]  Start the remote HTTP transport with OAuth (default port 3457)
orchyn-mcp login              Sign in to orchyn via Google in your browser
orchyn-mcp login --email ... --password ...   Password login
orchyn-mcp --help             Show help

Environment variables

How authentication works

stdio mode (Claude Desktop, Cursor): the server uses the token from ORCHYN_ACCESS_TOKEN or the credentials file written by login. If the token is expired it is automatically refreshed with the stored refresh token, and if the orchyn API returns 401 the request is retried once after a refresh.

HTTP mode (OpenAI Agents SDK, remote clients): the server runs its own OAuth 2.0 authorization server (Authorization Code + PKCE S256, public client, per the MCP 2025-03-26 spec):

• GET /.well-known/oauth-authorization-server — metadata
• GET /authorize — validates the request (loopback or https redirect URIs) and forwards the browser to orchyn's Google sign-in
• GET /oauth/callback — our own loopback callback; exchanges orchyn's completion code for orchyn JWTs and redirects back to the MCP client with a one-time code
• POST /token — verifies PKCE and issues an opaque Bearer token bound to the orchyn session (valid 1 hour)
• every MCP RPC validates the Bearer token against the session map

Supported URLs

• TikTok: tiktok.com/*, vm.tiktok.com/* (and www./m. subdomains)
• Instagram: instagram.com/* (reels, posts, carousels), instagr.am/*
• YouTube: youtube.com/* (including /shorts/), youtu.be/*, m.youtube.com/*
• X/Twitter: x.com/*, twitter.com/*
• Reddit: reddit.com/*, redd.it/*
• Weibo: weibo.com/*, weibo.cn/*
• Douyin: douyin.com/*
• Xiaohongshu: xiaohongshu.com/*, xhslink.com/*
• Bilibili: bilibili.com/*, b23.tv/*
• LinkedIn: linkedin.com/* (posts, profile URLs)

All tools accept these hosts and handle video, image, carousel, slideshow and text posts.

Troubleshooting

• Not authenticated with orchyn / 401: run npx @orchyn/mcp login or set ORCHYN_ACCESS_TOKEN.
• 402 paywall / insufficient MCP credits: your orchyn account is out of credits. Prices are listed per tool in Tools — 1 credit for a post lookup or transcript, 2-3 for discovery and the text-only AI tools, 6-15 for the ones that watch the video. The AI tools are free the first time you use each; data tools bill from the first call. Top up via buy_orchyn_credits, check_orchyn_credits, or the orchyn dashboard at https://orchyn.com/settings?tab=billing.
• Expired refresh token: the stored refresh token was rejected by the orchyn server. Run npx @orchyn/mcp login again to re-authenticate.
• Could not reach the orchyn server: ORCHYN_BASE_URL is unreachable or wrong.
• Client shows "Bad Request" or connection errors in HTTP mode: make sure the port matches ORCHYN_PUBLIC_URL and that the client fetched a token first (the OAuth flow must complete once in your browser).

Platform submissions

See docs/SUBMISSION.md for ready-to-paste configs and the submission package for Claude Desktop, Cursor, and OpenAI Agents SDK.

Security notes

• The credentials file is written with mode 0600 and the directory with 0700.
• OAuth redirect URIs are restricted to loopback (http://localhost, http://127.0.0.1, http://[::1]) or https:// URLs; the /authorize endpoint requires PKCE (S256).
• Authorization codes and PKCE challenges are one-time use and short-lived (in-memory).
• Access tokens are opaque, random, and bound to the in-memory session map; they expire after 1 hour. Restarting the server invalidates all sessions.
• Never share your credentials file or ORCHYN_ACCESS_TOKEN.

Development

npm install
npm run build    # tsc
npm test         # vitest (66 unit tests, mocked fetch — no network)

License

MIT