Pi YouTube Tools

Native Pi tools for YouTube search, video metadata, and transcripts — no MCP daemon required.

What this is

pi-youtube-tools is a native Pi extension that registers three YouTube tools via registerTool(). Install with pi install, configure an API key, and search or inspect videos without running a separate MCP server process.

This package targets the same workflows as external YouTube MCP servers, but ships as a Pi package: tools load in-process, auth stays local, and output is formatted for agent context limits.

Tools

Tool	Purpose
youtube_search	Search videos by query (default 5 results, max 10)
youtube_video_details	Title, channel, stats, optional truncated description
youtube_transcript	Fetch captions as hook/outro segments or capped full text

Slash commands

Command	Purpose
/youtube:login	Enter and store a YouTube Data API key via Pi UI
/youtube:status	Secret-safe check of whether an API key is configured
/youtube:logout	Remove the stored API key (does not unset YOUTUBE_API_KEY)

Install

pi install npm:pi-youtube-tools

Or install from GitHub:

pi install git:github.com/eiei114/pi-youtube-tools

API key setup

You need a YouTube Data API v3 key.

Auth precedence (first match wins):

1. YOUTUBE_API_KEY environment variable
2. Key stored by /youtube:login in ~/.pi/agent/pi-youtube-tools-auth.json (mode 600)

Configure with either method:

/youtube:login

$env:YOUTUBE_API_KEY="your_google_api_key"

Check configuration:

/youtube:status

/youtube:status reports configured or missing only — it never prints the key. /youtube:logout clears the stored file; an environment variable still takes precedence on the next run.

Typical workflow

1. Discover — youtube_search with a topic or game name.
2. Inspect — youtube_video_details for one or more videoId values from search results.
3. Read captions — youtube_transcript when spoken content matters.

youtube_transcript defaults to key_segments (intro hook + outro) to save tokens. Use format: full_text only when you need more of the transcript.

See docs/examples.md for copy-paste examples.

Output guards

Tool responses are formatted for LLM context and Pi clipboard/TUI limits:

• Overall tool text is capped at 12,000 characters.
• Search results default to 5 items (max 10); titles, channels, and snippets are compacted.
• Descriptions are truncated to 300 characters when includeDescription is true.
• Transcripts use 8,000 characters for full text or 2,000 per hook/outro segment.

Truncated sections end with a [truncated N chars] marker.

Quick start (local)

pi -e .

/youtube:login
/youtube:status

Then ask Pi to search YouTube, fetch video details, or read a transcript.

Package layout

Path	Purpose
extensions/	Pi extension entrypoints and tool registration
lib/	YouTube API client, auth, formatters, transcript helpers
docs/	Setup, examples, and release docs

Development

npm install
npm run ci

Release

This package uses npm Trusted Publishing (no NPM_TOKEN required).

npm version patch
git push --follow-tags

See docs/release.md for setup details.

Security

Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.

Never commit or log YOUTUBE_API_KEY. /youtube:login stores keys locally and the extension UI handles the secret without sending it to the model.

For vulnerability reporting, see SECURITY.md.

Links

• npm: https://www.npmjs.com/package/pi-youtube-tools
• GitHub: https://github.com/eiei114/pi-youtube-tools
• Issues: https://github.com/eiei114/pi-youtube-tools/issues

License

MIT