> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect from Claude Code

> Register the Pictory MCP server in Claude Code with one command, sign in with your Pictory account, and create videos from the terminal

This page registers the Pictory MCP server directly in [Claude Code](https://claude.com/claude-code).

<Note>
  If you have already added the [Pictory connector in Claude](/claude-mcp/claude-app) and Claude
  Code is signed in to the same account, you are done: `claude mcp list` shows it under the name
  you gave the connector, prefixed `claude.ai`, and its tools are available in every session. The steps below are for a
  machine that is not signed in to claude.ai, or for a project-wide setup shared with a team.
</Note>

## Prerequisites

* Claude Code installed: `npm install -g @anthropic-ai/claude-code`
* A Pictory account with a purchased Pictory API subscription: [app.pictory.ai](https://app.pictory.ai). A standard Pictory plan on its own is not enough.

## Add the server

```bash theme={null}
claude mcp add --transport http --callback-port 3118 pictory-ai-video https://mcp.pictory.ai/mcp
```

`pictory-ai-video` is the name you will use to refer to the server; any name works.
`--callback-port 3118` is required, see [why the callback port is fixed](#why-the-callback-port-is-fixed).

## Sign in

```bash theme={null}
claude mcp login pictory-ai-video
```

A browser window opens on the Pictory sign-in page. Sign in with your Pictory email and
password, or **Continue with Google**. The browser returns to Claude Code, which stores the
sign-in for future sessions.

You can also sign in from inside a session: type `/mcp`, select `pictory-ai-video`, and choose
**Authenticate**.

## Verify

```bash theme={null}
claude mcp list
```

The server shows as connected. Start a session and ask for a video:

```text theme={null}
claude
> Create a 30-second vertical teaser for a smart lamp. Futuristic look, upbeat music.
```

Claude settles a few details with you first (narration and voice, music, shape, whether to save
it as a project), then creates the video and gives you the link. A preview takes 2–5 minutes and
a final render 5–15 minutes.

## Why the callback port is fixed

Claude Code completes the sign-in on a local listener at `http://localhost:<port>/callback`.
Pictory's sign-in service checks that address against an exact list of registered return
addresses, and `http://localhost:3118/callback` is the one registered for Claude Code. Without
`--callback-port`, Claude Code picks a random free port for each sign-in, the address does not
match, and the sign-in page shows an error before you can log in. Always pass
`--callback-port 3118`.

## Scope

By default the server is registered for the current project only, for you. Two other scopes are
available:

| Scope             | Effect                                                                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--scope user`    | Available in every project on this machine                                                                                              |
| `--scope project` | Written to `.mcp.json` in the repository and shared with everyone who works in it. Each person signs in with their own Pictory account. |

For example, to make it available everywhere:

```bash theme={null}
claude mcp add --transport http --callback-port 3118 --scope user pictory-ai-video https://mcp.pictory.ai/mcp
```

## Sign out, refresh, remove

| Task                                        | Command                                     |
| ------------------------------------------- | ------------------------------------------- |
| Clear the stored sign-in                    | `claude mcp logout pictory-ai-video`        |
| Refresh the tool list without a new session | `/mcp` inside a session, then **Reconnect** |
| Remove the server                           | `claude mcp remove pictory-ai-video`        |

## Troubleshooting

<AccordionGroup>
  <Accordion title="The Sign-In Page Shows an Error Before You Can Log In">
    **Cause:** The server was added without `--callback-port`, so Claude Code used a random port
    and the return address did not match the registered one.

    **Resolution:**

    1. Remove the server: `claude mcp remove pictory-ai-video`
    2. Add it again with the flag: `claude mcp add --transport http --callback-port 3118 pictory-ai-video https://mcp.pictory.ai/mcp`
    3. Sign in: `claude mcp login pictory-ai-video`
  </Accordion>

  <Accordion title="Port 3118 Is Already in Use">
    **Cause:** Another process is listening on port 3118, so Claude Code cannot open the callback
    listener. The port cannot be changed, because it is the one registered with Pictory.

    **Resolution:**

    1. Find the process: `lsof -i :3118`
    2. Stop it, or wait for it to finish, then sign in again.
  </Accordion>

  <Accordion title="Tools Are Missing or Out of Date">
    **Cause:** Claude Code reads the server's tool list when it connects, so a tool added since
    then is not visible.

    **Resolution:**

    1. Type `/mcp` in the session, select `pictory-ai-video`, and choose **Reconnect**.
    2. If it is still missing, start a new session.
  </Accordion>

  <Accordion title="Calls Fail After a Successful Sign-In">
    **Cause:** The stored sign-in has expired, or the Pictory account does not carry a
    subscription that permits API use.

    **Resolution:**

    1. Sign out and in again: `claude mcp logout pictory-ai-video`, then `claude mcp login pictory-ai-video`
    2. Check your subscription at [app.pictory.ai](https://app.pictory.ai).
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Pictory MCP Server" icon="plug" href="/claude-mcp/overview">
    What the server can do, the tools, and the two design modes
  </Card>

  <Card title="Text-to-Video Skill" icon="wand-magic-sparkles" href="/claude-skills/text-to-video-setup">
    The Claude Code skill that works with your API key and carries its own design playbook
  </Card>
</CardGroup>