Skip to content
Back to search

youtube-mcp

Per-user YouTube Data API MCP server for MCP Runtime, authenticated through mcp-auth.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tavric-labs--youtube-mcp/badge.svg)](/listings/tavric-labs--youtube-mcp)

HTML

<a href="/listings/tavric-labs--youtube-mcp"><img src="/api/listings/tavric-labs--youtube-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You are the operator of the Google OAuth app. Each end user signs in with their own Google account and grants *your* app access to *their* channel.

1. **Google Cloud project.** Create one, and enable **YouTube Data API v3**. 2. **OAuth consent screen.** Set the app name, support email and authorized domains. Add the scope `https://www.googleapis.com/auth/youtube.force-ssl` (it covers everything this server does, including upload; if you only need read tools, `youtube.readonly` is narrower). 3. **OAuth client.** Create a client of type **Web application**. Add the authorized redirect URI `<MCP Auth issuer URL>/identity/callback`. Keep the client ID and secret. 4. **Secrets.** Generate an RSA key pair for this server's resource client. Put the private key in the `youtube-mcp-client-key` Secret (`YOUTUBE_MCP_CLIENT_KEY`) and the public key in `.mcp/auth-resource.yaml`. Put `YOUTUBE_CLIENT_SECRET` in `mcp-auth-connector-secrets`. Nothing secret goes in a file in this repo. 5. **Deploy and wire sign-in.** `.mcp/servers.yaml` declares outbound `www.googleapis.com:443` for the YouTube Data and upload APIs. The platform administrator must separately approve this egress after deploy. Runtime records the hostname but its Kubernetes policy can enforce only TCP/443 to public IPs; it cannot enforce the hostname. Run `server validate`, `server build image`, `server push`, and `server deploy` with `.mcp/servers.yaml`; then fill `.mcp/auth-resource.yaml` and apply it with `mcp-runtime cluster mcp-auth resource apply --file .mcp/auth-resource.yaml` (needs mcp-runtime v0.18.0 or newer; v0.5.2 does not have this command). 6. **Run one replica.** Staged files and saved upload sessions live on the pod's disk. The image creates `/var/lib/youtube-mcp/media` for the non-root user; it is **ephemeral** unless you mount a volume there (not verified that `servers.yaml` can declare one). After a restart staged files and saved sessions are gone and the person stages the file again.

Consent screen and verification

`youtube.force-ssl` and `youtube.upload` are **sensitive** scopes. While the consent screen is in **Testing**, only the test users you list (up to 100) can sign in, and Google issues their refresh tokens for 7 days only. To let anyone sign in you must publish the app and pass Google's **OAuth verification** (privacy policy, homepage, a demo video of the scope in use). Until then users see an "unverified app" warning and are capped at 100.

API quota

The YouTube Data API gives a project **10,000 units a day by default**, resetting at midnight Pacific Time. Approximate costs (check Google's current quota calculator, they change):

| Call | Units | |---|---| | `videos.insert` (an upload) | 1600 | | `videos.update`, `playlists.insert`, `playlistItems.insert`, `comments.insert`, `comments.setModerationStatus`, deletes | 50 | | any list or read | 1 | | `search.list` (not used) | 100 |

So the default quota is about **six uploads a day for the whole project**, shared by every user. When it runs out tools answer that the quota is used up. More quota needs Google's quota-extension audit.

Unverified API projects upload private

Videos uploaded through the API by a project that has **not passed Google's YouTube API compliance audit** are locked to **private**, whatever `privacy` you ask for. The upload tool reports this when it happens ("YouTube kept it private"). Until the audit passes, uploads can be reviewed and then published by hand in YouTube Studio. This is Google policy, not something the server can work around.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 233 lines
  1. # youtube-mcp
  2. An MCP server that lets a signed-in person manage **their own YouTube channel**:
  3. read it, upload and update videos, organise playlists and moderate comments. It is
  4. built to run on [MCP Runtime](https://github.com/tavric-labs/mcp-runtime) behind
  5. [mcp-auth](https://github.com/tavric-labs/mcp-auth), the same way
  6. [instagram-mcp](https://github.com/tavric-labs/instagram-mcp) does.
  7. > **Status: deployed as `org/youtube:0.1.0` with one ready replica.** The current
  8. > implementation has only been tested against fake Google and YouTube endpoints;
  9. > a real sign-in, token exchange, and YouTube API call still need end-to-end
  10. > verification. See [Known gaps](#known-gaps) before relying on it.
  11. ## How it works
  12. 1. The MCP client signs the person in through mcp-auth (Sign in with Google) and sends
  13. the resulting access token to this server.
  14. 2. The server verifies the token (`mcpauth.RequireToken`, audience = this server's URL).
  15. 3. For each tool call it exchanges that token for **that person's own Google token**
  16. (RFC 8693, authenticating as a resource client with `private_key_jwt`) and calls
  17. the YouTube Data API as them.
  18. There is **no shared owner token and no service account**. Every call acts as the signed-in
  19. Google account, so it can only touch what that account can touch. The server stores no
  20. Google token and caches nothing: revoking a person's mcp-auth session stops their YouTube
  21. calls at once. Audit comes from the MCP Runtime gateway; the server logs subject, tool and
  22. outcome, never a token, session URI, comment or caption text.
  23. ## Tools
  24. Every tool that changes YouTube is a **dry run unless `confirm: true`**, and needs the
  25. `tools:write` scope when confirmed. A dry run touches nothing, not even the token exchange.
  26. | Tool | Scope | What it does |
  27. |---|---|---|
  28. | `youtube_get_channel` | `tools:read` | The person's own channel: title, handle, counts. |
  29. | `youtube_list_videos` | `tools:read` | Uploads, newest first, via the uploads playlist (1 quota unit, not search's 100). |
  30. | `youtube_get_video` | `tools:read` | One video's details and processing state. |
  31. | `youtube_upload_video` | `tools:write` | Uploads a staged file. Private by default. Resumable and idempotent. |
  32. | `youtube_update_video` | `tools:write` | Title, description, tags, category, privacy. Reads the video, merges, writes back, so fields not named are kept. |
  33. | `youtube_list_playlists` | `tools:read` | The person's playlists. |
  34. | `youtube_create_playlist` | `tools:write` | Creates a playlist (private by default); returns the existing one if the title exists. |
  35. | `youtube_add_playlist_item` | `tools:write` | Adds a video; a no-op if it is already there. |
  36. | `youtube_remove_playlist_item` | `tools:write` | Removes one playlist entry (the video stays). |
  37. | `youtube_list_comments` | `tools:read` | Top-level comment threads. Output is labelled as untrusted viewer text. |
  38. | `youtube_reply_to_comment` | `tools:write` | Replies as the person. Sent once, never auto-retried. |
  39. | `youtube_moderate_comment` | `tools:write` | Publish, hold for review or reject (optionally ban the author) on the person's own videos. |
  40. | `youtube_delete_comment` | `tools:write` | Permanent. |
  41. Comment text is written by strangers. The server marks it as data in the tool output and in
  42. the tool description; a client should still never treat it as an instruction.
  43. ### Uploading a video
  44. A video is too large for a tool argument, so it is staged over HTTP first, then uploaded by
  45. asset id:
  46. ```bash
  47. # 1. Stage the file for your own account (needs a token with tools:write).
  48. curl -X POST "$SERVER/media" \
  49. -H "Authorization: Bearer $MCP_ACCESS_TOKEN" \
  50. -H "Content-Type: video/mp4" \
  51. --data-binary @video.mp4
  52. # -> {"asset_id":"3f2a...","bytes":...,"sha256":"..."}
  53. # 2. In your MCP client: youtube_upload_video with that asset_id, a title, privacy and
  54. # made_for_kids. Repeat the identical call until it reports the video id.
  55. ```
  56. - `/media` is also served at `<MCP path>/media` (for example `/youtube/mcp/media`), because a
  57. gateway may route only the prefix it was given for the MCP endpoint. **Which of the two is
  58. reachable through your gateway has not been verified.**
  59. - Accepted: `video/mp4`, `video/quicktime`, `video/webm`, checked against the file's first
  60. bytes. At most 2 GiB per file, 8 files and 4 GiB per person. Staged files are deleted after
  61. 24 hours.
  62. - `made_for_kids` has no default: it is a legal declaration, so the caller must say.
  63. - One `youtube_upload_video` call sends for up to about 40 seconds. For a large file it
  64. returns "in progress: X of Y MiB"; **call it again with the same arguments** and it resumes
  65. where it stopped. A call that is repeated after a crash, a timeout or a success never
  66. uploads the file twice: progress is saved per person and asset, bound to a fingerprint of
  67. the file bytes and the requested details, and a finished result is remembered. Asking for
  68. *different* details after a finished upload is refused and points to `youtube_update_video`.
  69. ## Configuration
  70. | Variable | Purpose |
  71. |---|---|
  72. | `YOUTUBE_MCP_RESOURCE` | This server's public MCP URL (the token audience). |
  73. | `YOUTUBE_MCP_ISSUER` | The mcp-auth issuer URL. `YOUTUBE_JWKS_URL` overrides discovery. |
  74. | `YOUTUBE_MCP_CLIENT_ID`, `YOUTUBE_MCP_CLIENT_KEY_ID` | The resource client registered in mcp-auth. |
  75. | `YOUTUBE_MCP_CLIENT_KEY` or `YOUTUBE_MCP_CLIENT_KEY_FILE` | The client's RSA private key (PEM). |
  76. | `YOUTUBE_MCP_MEDIA_DIR` | Staging directory, absolute. Default `/var/lib/youtube-mcp/media`. |
  77. | `YOUTUBE_API_BASE`, `YOUTUBE_UPLOAD_BASE` | Default to the public YouTube Data API v3 endpoints; tests and proxies override them. |
  78. | `MCP_PATH`, `PORT` | Default `/mcp` and `8080`. |
  79. | `YOUTUBE_MCP_ALLOW_INSECURE=true` | Plain http issuer, local development only. |
  80. ## Operator setup
  81. You are the operator of the Google OAuth app. Each end user signs in with their own Google
  82. account and grants *your* app access to *their* channel.
  83. 1. **Google Cloud project.** Create one, and enable **YouTube Data API v3**.
  84. 2. **OAuth consent screen.** Set the app name, support email and authorized domains. Add the
  85. scope `https://www.googleapis.com/auth/youtube.force-ssl` (it covers everything this
  86. server does, including upload; if you only need read tools, `youtube.readonly` is
  87. narrower).
  88. 3. **OAuth client.** Create a client of type **Web application**. Add the authorized redirect
  89. URI `<MCP Auth issuer URL>/identity/callback`. Keep the client ID and secret.
  90. 4. **Secrets.** Generate an RSA key pair for this server's resource client. Put the private
  91. key in the `youtube-mcp-client-key` Secret (`YOUTUBE_MCP_CLIENT_KEY`) and the public key in
  92. `.mcp/auth-resource.yaml`. Put `YOUTUBE_CLIENT_SECRET` in `mcp-auth-connector-secrets`.
  93. Nothing secret goes in a file in this repo.
  94. 5. **Deploy and wire sign-in.** `.mcp/servers.yaml` declares outbound
  95. `www.googleapis.com:443` for the YouTube Data and upload APIs. The platform
  96. administrator must separately approve this egress after deploy. Runtime records
  97. the hostname but its Kubernetes policy can enforce only TCP/443 to public IPs;
  98. it cannot enforce the hostname. Run `server validate`, `server build image`,
  99. `server push`, and `server deploy` with `.mcp/servers.yaml`; then fill
  100. `.mcp/auth-resource.yaml` and apply it with
  101. `mcp-runtime cluster mcp-auth resource apply --file .mcp/auth-resource.yaml` (needs mcp-runtime v0.18.0 or newer; v0.5.2 does not have this command).
  102. 6. **Run one replica.** Staged files and saved upload sessions live on the pod's disk. The
  103. image creates `/var/lib/youtube-mcp/media` for the non-root user; it is **ephemeral** unless
  104. you mount a volume there (not verified that `servers.yaml` can declare one). After a
  105. restart staged files and saved sessions are gone and the person stages the file again.
  106. ### Consent screen and verification
  107. `youtube.force-ssl` and `youtube.upload` are **sensitive** scopes. While the consent screen is
  108. in **Testing**, only the test users you list (up to 100) can sign in, and Google issues their
  109. refresh tokens for 7 days only. To let anyone sign in you must publish the app and pass
  110. Google's **OAuth verification** (privacy policy, homepage, a demo video of the scope in use).
  111. Until then users see an "unverified app" warning and are capped at 100.
  112. ### API quota
  113. The YouTube Data API gives a project **10,000 units a day by default**, resetting at midnight
  114. Pacific Time. Approximate costs (check Google's current quota calculator, they change):
  115. | Call | Units |
  116. |---|---|
  117. | `videos.insert` (an upload) | 1600 |
  118. | `videos.update`, `playlists.insert`, `playlistItems.insert`, `comments.insert`, `comments.setModerationStatus`, deletes | 50 |
  119. | any list or read | 1 |
  120. | `search.list` (not used) | 100 |
  121. So the default quota is about **six uploads a day for the whole project**, shared by every
  122. user. When it runs out tools answer that the quota is used up. More quota needs Google's
  123. quota-extension audit.
  124. ### Unverified API projects upload private
  125. Videos uploaded through the API by a project that has **not passed Google's YouTube API
  126. compliance audit** are locked to **private**, whatever `privacy` you ask for. The upload tool
  127. reports this when it happens ("YouTube kept it private"). Until the audit passes, uploads can
  128. be reviewed and then published by hand in YouTube Studio. This is Google policy, not something
  129. the server can work around.
  130. ## Google offline access (read this)
  131. **Short answer: durable refresh does not work with mcp-auth as it stands, and this server does
  132. not pretend otherwise.**
  133. What the mcp-auth code shows (inspected under `mcp-auth/auth-server/server/`, at commit
  134. `b0234fb`):
  135. - The upstream authorization URL is built in `oidc.go` from a fixed set of parameters
  136. (`response_type`, `client_id`, `redirect_uri`, `scope`, `state`, PKCE, and `nonce` when
  137. needed). The connector configuration (`ConnectorConfig` in `connectors.go`) has **no field
  138. for extra authorization parameters**, and no non-test code anywhere in the server mentions
  139. `access_type` or `prompt`.
  140. - The `upstream_session` strategy this server relies on does refresh an expired upstream token
  141. with `grant_type=refresh_token` (`upstream_session.go`), but only when the provider returned a
  142. refresh token at sign-in; otherwise it answers *"upstream session expired and has no refresh
  143. token"*.
  144. - Google returns a refresh token to a web-server OAuth client **only when the authorization
  145. request carries `access_type=offline`** (and, to get a new one on a repeat consent,
  146. `prompt=consent`). That is Google's documented behaviour; I have not observed it live.
  147. So: the Google access token mcp-auth holds lasts about **one hour** and cannot be renewed. After
  148. that, tool calls fail with "Sign in again from your MCP client" until the person signs in
  149. again. That is fine for short interactive sessions, **not** for unattended automation, and a
  150. large upload that outlives the token will stop and need a fresh sign-in (the saved upload
  151. session survives, so the retry resumes).
  152. Workarounds I considered and did **not** rely on:
  153. - Putting `access_type=offline&prompt=consent` in `authorization_endpoint`: `oidc.go` appends
  154. `"?" + params` to that string, so a URL that already has a query would come out malformed
  155. (by reading the code; not tried).
  156. - A shared owner token or service account: rejected on purpose; it would break per-user
  157. isolation.
  158. The real fix is in mcp-auth: an optional per-connector map of extra authorization parameters
  159. (for Google, `access_type=offline` and `prompt=consent`), and then a live test that a refresh
  160. token is stored and used. Until that lands and is verified, treat every Google session as
  161. one hour long. Also note that while the Google consent screen is in *Testing*, refresh tokens
  162. expire after 7 days even once this works.
  163. ## Security notes
  164. - **Per-person isolation.** Staged files live in a directory named by a hash of the verified
  165. token subject, mode 0700; every operation takes the subject from the verified token and
  166. accepts no path or other person's id. Asset ids are validated as 32 hex characters and opened
  167. through `os.Root`. Tests cover reading, writing state, deleting, resuming and uploading
  168. across two subjects.
  169. - **Resumable session URIs are secrets.** Together with the person's token a session URI can
  170. write to YouTube. It is stored only in a 0600 file, never logged, never returned to the
  171. caller, and is checked to point at the upload host before the token is ever sent to it.
  172. - **No upstream text leaks.** Errors keep only the HTTP status and Google's short reason code.
  173. - **Retries.** Reads, PUT and DELETE are retried with backoff on network errors, 429 and 5xx.
  174. POST (create playlist, reply, moderate) is sent once so it cannot duplicate; the playlist and
  175. playlist-item tools check for an existing match first.
  176. - **Limits.** Size, type (by magic bytes), per-person count and bytes, and a 24-hour sweep.
  177. ## Known gaps
  178. - The fake server follows Google's documented upload protocol but is not Google. A real
  179. sign-in, token exchange and API call have not been verified yet; expect surprises on the
  180. first live upload.
  181. - Offline access (above). Sessions are one hour.
  182. - The staging area is a single pod's disk: one replica, ephemeral without a volume, and a 2 GiB
  183. file needs that much free node storage.
  184. - Whether the gateway routes `/media` (or `<MCP path>/media`) to the pod is unverified.
  185. - Playlist/title duplicate checks look at the first 200 playlists only.
  186. - `videos.update` is read-modify-write without an ETag precondition, so a concurrent edit in
  187. YouTube Studio between the read and the write can be overwritten.
  188. - The Dockerfile and CI were written but the image build was **not run** here (no Docker daemon).
  189. ## Develop
  190. ```bash
  191. gofmt -l . && go vet ./... && go test -race ./... && go build ./...
  192. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.