Metadata-Version: 2.4
Name: gen-mcp-server
Version: 0.1.27
Summary: GEN is an autonomous social media agent: it spots trends, writes scripts, and creates videos. Official MCP server for Claude Code, Cursor, and VS Code.
Project-URL: Homepage, https://gen.pro
Project-URL: Documentation, https://api.gen.pro
Project-URL: Repository, https://github.com/poweredbyGEN/gen-agentic
Author: GEN
License: MIT
Keywords: ai,content,gen,gen-pro,mcp,video
Requires-Python: >=3.10
Requires-Dist: fastmcp>=3.4.2
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# GEN — gen-mcp-server

<!-- mcp-name: io.github.poweredbyGEN/gen-mcp-server -->

**GEN is an autonomous social media agent: it spots trends, writes scripts, and creates videos** — across 10+ platforms, and publishes to TikTok, Instagram, Facebook, YouTube, and X. This is the official MCP server for [GEN](https://gen.pro): everything the agent does, available from Claude Code, Cursor, or VS Code.

Every other tool does one step. GEN runs the whole loop:

```
Spot  →  Script  →  Create  →  Publish  →  Learn  →  repeat
trends    ideas     video      post       results
```

You're not operating a tool. You're directing an agent that does the work — then keeps doing it.

## What you can do from your client

**Spot trends — read what's actually working.** Ask about any uploaded media attachment, video link, account, hashtag, trend, sound, hook, or comment and get a real answer from GEN's social warehouse (TikTok, Instagram, YouTube + more) plus media analysis when actual files are available: why a video performed, what's rising in a niche, an account's hooks and stats, how an audience is reacting. The agent reads trends *before* it creates — it doesn't generate blind.

**Write scripts & ideas — turn the signal into a plan.** Data-driven content ideas tuned to your niche, then readable scripts, narrations, ad reads, stories, and hooks built from what is already working.

**Create videos — from idea to finished cut.** Complete multi-scene videos (avatar, B-roll, captions, voice, music, render) — or any single piece on demand.

**Publish & run it on autopilot.** Post to TikTok, Instagram, Facebook, YouTube, and X; or hand the agent a standing goal and it runs the whole loop on a schedule — spot, script, create, publish — without you in the seat.

Direct posting API: `POST https://agent.gen.pro/v1/post` with your GEN PAT in
`X-API-Key`. Send `schedule_type: "now"` to publish immediately, or
`schedule_type: "specific_time"` with an ISO8601 `scheduled_time` to post later.

Post now:

```bash
curl -X POST https://agent.gen.pro/v1/post \
  -H "X-API-Key: YOUR_GEN_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "platform": "instagram",
    "media_url": "https://assets.gen.pro/videos/example.mp4",
    "description": "Launch day",
    "schedule_type": "now"
  }'
```

Post later:

```bash
curl -X POST https://agent.gen.pro/v1/post \
  -H "X-API-Key: YOUR_GEN_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "platform": "instagram",
    "media_url": "https://assets.gen.pro/videos/example.mp4",
    "description": "Launch day",
    "schedule_type": "specific_time",
    "scheduled_time": "2026-06-25T18:00:00Z"
  }'
```

## How you drive it

- **`gen_ask`** — ask GEN anything about real social data or media attachments (uploaded image/video/audio/doc/spreadsheet, YouTube/TikTok/Instagram link, account, hashtag, trend, sound, comment). One front door; the agent figures out what to pull or analyze.
- **`gen_generate_content_ideas`** / **`gen_research`** / **`gen_make_video`** — named shortcuts for the moves you reach for most. Use `gen_generate_content_ideas(output="scripts")` for direct spoken/readable script requests, `purpose="voiceover"` / `"ad read"` / `"short story"` when known, and `script_only=true` when the user asks for no explanation.
- **`gen_chat`** — hand the agent any open-ended, multi-step goal and let it run. Pass uploaded media refs in `attachments` when the goal depends on a file; leave YouTube/social links in the goal text.
- **~60 deterministic `gen_*` tools** for exact single actions (create one image/video/song, render, schedule, manage assets/voices/credits).
- Ask *"what can you do?"* anytime — the agent lists its full, current playbook.

## Quick start

GEN is **hosted** — connect to a URL, nothing to install. The server lives at
**`https://mcp.gen.pro/mcp`** over streamable HTTP, and each caller sends its own
PAT as a bearer token (multi-tenant).

Get a Personal Access Token first at **[gen.pro](https://gen.pro)** → log in → pick
an agent → **API** page → Create API Key.

**Claude Code:**

```bash
claude mcp add --transport http GEN https://mcp.gen.pro/mcp \
  --header "Authorization: Bearer YOUR_GEN_PAT"
```

**Cursor / VS Code / claude.ai connectors / ChatGPT / Manus** — add a remote
(streamable-HTTP) server:

- **Server URL:** `https://mcp.gen.pro/mcp`
- **Authentication:** Bearer token → your `gen_…` PAT

In raw `mcp.json` form:

```json
{
  "mcpServers": {
    "GEN": {
      "type": "http",
      "url": "https://mcp.gen.pro/mcp",
      "headers": { "Authorization": "Bearer YOUR_GEN_PAT" }
    }
  }
}
```

Why hosted and not a local install: a local copy is a **thin client** — it still
needs a `GEN_API_KEY` and still calls `agent.gen.pro`, so it buys nothing except a
version you have to remember to update. Worse, a stale install pins **old tool
schemas**. Remote means a fix lands once and every caller has it immediately.

## Self-hosting (optional)

You can still run the HTTP transport yourself from a checkout:

```bash
gen-mcp-server --http     # serves 0.0.0.0:8080/mcp
```

Override the bind with `GEN_MCP_HOST` / `GEN_MCP_PORT`. Callers authenticate with
`Authorization: Bearer <gen_PAT>`, exactly as with the hosted endpoint. A stdio
entrypoint (`gen-mcp-server`, reading `GEN_API_KEY` from the environment) also
still exists for local development.

> **Note:** `server.json` advertises the hosted remote only. The PyPI package is
> not the supported distribution path — see `docs/transport.md`.

## Setup

- **Transport:** streamable HTTP at `https://mcp.gen.pro/mcp` (supported), or a
  self-hosted `--http` / stdio process for local development.
- **Auth:** `Authorization: Bearer <PAT>` (hosted) or `GEN_API_KEY` env (stdio).

The env vars below apply to a **self-hosted / stdio** process. Against the hosted
endpoint you send only the bearer token — there is nothing to configure.

| Var | Required | Default |
| --- | --- | --- |
| `GEN_API_KEY` | stdio only | — |
| `GEN_API_BASE_URL` | no | `https://api.gen.pro/v1` |
| `GEN_AGENT_API_URL` | no | `https://agent.gen.pro/v1` |
| `GEN_AGENT_CORE_API_URL` | no | `https://agent-core.gen.pro/v1` |

## Credits

GEN is credit-based: generation, voice, and research cost credits; reads and CRUD are free. On an empty balance, tools return `insufficient_credits`. Price a job first with `gen_estimate_job`; check your balance with `gen_get_credit_balance`.

To top up, use:

- `gen_buy_credits` for Stripe checkout.
- `gen_create_x402_credit_quote` for USDC via x402.

The x402 quote returns `payment_methods` plus `payment_required.accepts`. If you do not pass `network`, GEN lists every configured option instead of choosing silently. Show the user or calling agent the available Sui, Solana, and Base options, then sign and retry with the selected method. Workspace funding wallets are backend infrastructure; the user-facing choice is the `payment_methods` list.

---

Built by [GEN](https://gen.pro) — the end of managing social media. · [API docs](https://api.gen.pro)
