# YtMCP Quick Start Guide
## 🚀 5-Minute Setup
### Option 1: Local Development (STDIO)
```bash
# 1. Navigate to project
cd "d:/Program Files (x86)/YtMCP"
# 2. Install dependencies
uv sync
# 3. Run server
uv run ytmcp
```
**✅ Server is now running!** Connect your MCP client (see below).
---
### Option 2: Production Deployment (Render)
```bash
# 1. Push to GitHub (if not already done)
git init
git add .
git commit -m "Initial commit"
git remote add origin <your-repo-url>
git push -u origin main
# 2. Go to render.com
# 3. New Web Service → Connect your repo
# 4. Render auto-detects render.yaml → Click "Create"
# 5. Wait 2-3 minutes for deployment
# 6. Verify (replace with your URL)
curl https://ytmcp-<random>.onrender.com/health
```
**✅ Production server deployed!** Connect via HTTPS (see below).
---
## 🔌 Connect MCP Clients
### Gemini CLI
**Edit:** `.gemini/mcp_config.json`
```json
{
"mcpServers": {
"ytmcp-local": {
"command": "uv",
"args": ["run", "--directory", "d:/Program Files (x86)/YtMCP", "ytmcp"]
},
"ytmcp-prod": {
"url": "https://your-app.onrender.com/mcp"
}
}
}
```
**Restart Gemini CLI**, then use tools like:
```
search_videos_tool(query="AI tutorials", limit=5)
```
---
### Claude Desktop
**Edit:** `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac)
or `%APPDATA%/Claude/claude_desktop_config.json` (Windows)
```json
{
"mcpServers": {
"ytmcp": {
"command": "uv",
"args": ["--directory", "d:/Program Files (x86)/YtMCP", "run", "ytmcp"]
}
}
}
```
**Restart Claude Desktop**, tools appear automatically.
---
### Cursor
**Create:** `.cursor/mcp.json` in your project
```json
{
"mcpServers": {
"ytmcp": {
"command": "uv",
"args": ["--directory", "d:/Program Files (x86)/YtMCP", "run", "ytmcp"]
}
}
}
```
**Restart Cursor**, access tools via chat.
---
## 🧪 Test Your Setup
### Test 1: Search Videos
```
Use search_videos_tool to find 5 Python tutorials
```
**Expected:** Markdown list with titles, channels, URLs
---
### Test 2: Get Transcript
```
Get the transcript for video: dQw4w9WgXcQ
```
**Expected:** Time-synced transcript with timestamps
---
### Test 3: Channel Analysis
```
List the 10 most popular videos from @fireship
```
**Expected:** Sorted list with view counts and URLs
---
## 📊 Available Tools (16 Total)
### 🔍 Search (5 tools)
- `search_videos_tool` - Basic keyword search
- `search_filtered_tool` - Advanced search with filters
- `get_trending_videos_tool` - Current trending videos
- `find_channels_tool` - Search for channels
- `find_playlists_tool` - Search for playlists
### 🎥 Video Intelligence (5 tools)
- `get_transcript_tool` - Extract transcripts
- `get_video_metadata_tool` - Get video details
- `get_video_chapters_tool` - Extract chapters
- `get_thumbnail_tool` - Get thumbnail URLs
- `get_comments_tool` - Fetch top comments
### 📊 Channel Analysis (5 tools)
- `get_channel_videos_tool` - List channel videos
- `get_channel_shorts_tool` - List channel Shorts
- `get_channel_streams_tool` - List live streams
- `get_playlist_items_tool` - Get playlist contents
- `get_channel_about_tool` - Channel information
### 🛠️ Utilities (1 tool)
- `get_audio_stream_url_tool` - Get audio stream URL
---
## 🐛 Troubleshooting
### "Server not responding"
**Local (STDIO):**
```bash
# Check if server is running
ps aux | grep ytmcp
# Restart
uv run ytmcp
```
**Production (HTTPS):**
```bash
# Check health
curl https://your-app.onrender.com/health
# Should return: {"status": "healthy", ...}
```
---
### "Tool execution takes long time"
**Expected:** First request after server start takes 1-2s (imports)
**Rate Limiting:** 0.75s delay between YouTube requests is intentional
**Comments Tool:** Slower by design (fetches full HTML), use sparingly
---
### "Import errors"
```bash
# Reinstall dependencies
uv sync --reinstall
# Verify installation
uv run python -c "import ytmcp; print('OK')"
```
---
## 🎯 Common Use Cases
### Use Case 1: Research Trending Topics
```
1. Get trending videos
2. For each video, get transcript
3. Analyze content for patterns
```
### Use Case 2: Channel Competitor Analysis
```
1. Find channels in your niche
2. Get their most popular videos
3. Analyze metadata (tags, descriptions)
4. Get transcripts for content analysis
```
### Use Case 3: Playlist to Knowledge Base
```
1. Get playlist items
2. For each video:
- Get transcript
- Get metadata
- Extract key insights
```
---
## 📚 Next Steps
1. **Read Full Docs:** `README.md`
2. **Deploy to Production:** `docs/DEPLOYMENT.md`
3. **Understand Architecture:** `PROJECT_SUMMARY.md`
4. **Library Research:** `research/` folder
---
## 🆘 Need Help?
- **GitHub Issues:** Report bugs
- **Documentation:** Check README.md
- **MCP Community:** Discord/Forums
---
**🎉 You're ready to use YtMCP!**
Start by testing a simple search, then explore all 16 tools.
**Happy building!** 🚀
