creatorlens
Provides read-only YouTube channel analytics via Google's official YouTube APIs: signs in channels, creates Reporting jobs, downloads daily report files into a local archive, and exposes status, store-description, and sandboxed SQL query tools over the local analytics data.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
creatorlens
Read-only channel analytics for YouTube, for your AI assistant (MCP). A local server and command line that keeps your own channel's analytics on your computer, through Google's official APIs, with two read-only scopes.
creatorlens is not affiliated with, endorsed by or sponsored by YouTube or Google. "YouTube" is a trademark of Google LLC.
Status: v0 (0.1.0). v0 saves your history from day one: it signs in each channel, creates the YouTube Reporting API jobs, downloads every daily report file into a local archive, keeps the policy clocks, and runs every morning. Its MCP server answers
status,describe_storeandsql_query. The analysis tools (channel_review,video_report,video_card,video_retention,channel_traffic,channel_reach,channel_audience,compare,metadata_checkand more) arrive in v1, which parses the archive v0 keeps. Nothing of the history is lost meanwhile: Google keeps report files for 60 days, and creatorlens keeps them for as long as your authorization holds.Not on npm. Install from this repository; never run an
npx creatorlensline, which would fetch someone else's package.
Why
Impressions and click-through exist only in the Reporting API's files, Google keeps those files 60 days, and a job brings only the 30 days before it was created. A job must exist from the first day and its files must be kept.
An assistant answers better from your real figures than from guesses, and a local store answers a year of questions in milliseconds with no quota.
Every existing server we read either asks for write and delete scopes, has write tools that cannot be turned off, or sends your requests to a third party. creatorlens is read-only by construction.
Related MCP server: SQL MCP Server
The safety model
Two read-only scopes:
youtube.readonlyandyt-analytics.readonly. A sign-in that grants any other scope is revoked and refused, and a token that later carries one is refused. creatorlens has no way to upload, edit, delete, comment or change your channel.A closed route table: every request is checked against a list of method, host, path and caller before it is sent. Only Google's API and sign-in hosts are listed (not even
www.googleapis.com). Redirects are refused, except a report download redirected to another download route; your token never goes to another host.The few state-changing calls are yours alone: creating and deleting Reporting jobs and revoking a token live in a module the MCP server never imports, so no tool can reach them, and the server also sets a one-way read-only latch. On the command line they need a terminal, a typed confirmation and a shell no AI assistant started (see "Settings for the folder where you use it" for what that does and does not stop).
Everything stays local: a SQLite store and a raw archive per channel in
~/Library/Application Support/creatorlens/(folders 0700, files 0600), the tokens in the macOS Keychain. No telemetry, no network service.Strangers' text is data: text other people write (search terms, referrer pages and, from v2, comments) is cleaned and returned only wrapped as
{"untrusted": "…"}, in every tool and in SQL results too.SQL in a sandbox:
sql_queryruns one read-only statement in a separate process with an empty environment,limitsthat stopATTACHandVACUUM INTO, a deny-by-default authorizer, and a kill after 5 seconds.The policy clocks: revoking through creatorlens deletes everything in the same run; a sign-in that can no longer be refreshed is announced in every answer and purged 28 days after the last good refresh; your videos' metadata (every field but the ids) is deleted if not refreshed for 30 days; other channels' data (v2) never lives longer than 30 days. The clocks run even when a scheduled sync stops for unaccepted terms. See docs/policy.md.
What the Keychain does not do, and what to do if a token leaks: SECURITY.md.
Privacy: who sees your data
Your data stays on your computer, but everything a creatorlens tool returns goes to your AI client and on to its
model provider (for Claude: Anthropic), and stays in the client's transcripts under the client's retention setting
(cleanupPeriodDays in Claude Code). Connecting creatorlens to a client is your choice of that provider for this data.
creatorlens's own purges cannot reach those copies, except in transcript folders you name with
creatorlens transcripts add <folder>, which every full purge empties. The full policy:
docs/privacy.md. Terms: docs/terms.md.
Requirements
macOS (Linux arrives in v2; Windows is not supported).
Node.js 24.15 or later; 26.7.0 is the tested and pinned version.
node:sqliteneeds 24.15 for itslimits.pnpm 10.28 (the version in
package.json).A Google account that owns or manages the channel, and about 40 minutes in Google Cloud the first time.
Production dependencies: @modelcontextprotocol/server 2.4.0 and zod 4.6.7, which bring one more package
(@modelcontextprotocol/core): three packages in all. Development: typescript and @types/node. No install scripts.
Set up
The full checklist, with every Google Cloud screen: docs/owner-setup.md. In short:
git clone https://github.com/yrkan/creatorlens.git && cd creatorlens
pnpm install --frozen-lockfile && pnpm build && pnpm test
sh scripts/install-hooks.sh # gitleaks before every commit (for contributors)
node dist/cli.js install # a pinned copy outside the clone; it prints its path
APP="$HOME/Library/Application Support/creatorlens/app/0.1.0/cli.js"
node "$APP" setup --client-json ~/Downloads/client_secret_*.json
node "$APP" auth --profile en # one profile per channel: en, es, ru, …
node "$APP" reporting enable --profile en
node "$APP" sync --profile en --full
node "$APP" schedule install --profile en # daily at 07:30, and at login
node "$APP" doctor --json # green when everything is in place
node "$APP" mcp-config # prints the next line with your paths
cd ~/channel-analysis && claude mcp add --scope local creatorlens -- <node> "$APP" serveSecrets go only into your own terminal: never paste a token, the client JSON or an API key into a chat.
Settings for the folder where you use it
--scope local registers the server only in the folder where you run the command. The MCP server itself cannot sign
in, create or delete Reporting jobs, revoke, or read the token. What can is a shell: anything running as you can read
the Keychain item and the data folder (SECURITY.md), and a shell can open a pseudo-terminal (script, expect) and
type a confirmation. So in that folder:
Keep the assistant's shell on "ask" (no blanket
Bashallow, no auto-approve mode), and its web fetches and other servers' write tools too, above all while it reads text strangers wrote. This is the wall.Add the deny rules to that folder's
.claude/settings.json(creatorlens mcp-configprints this block with your paths). They catch a direct attempt; a Bash rule matches the command as written, so a wrapped one (sh -c,script, a variable) passes. They are a net, not a wall.
{
"permissions": {
"deny": [
"Bash(*security find-generic-password*)",
"Bash(*security dump-keychain*)",
"Bash(*cli.js* auth*)", "Bash(*creatorlens auth*)",
"Bash(*cli.js* setup*)", "Bash(*creatorlens setup*)",
"Bash(*cli.js* revoke*)", "Bash(*creatorlens revoke*)",
"Bash(*cli.js* purge*)", "Bash(*creatorlens purge*)",
"Bash(*cli.js* reporting*)", "Bash(*creatorlens reporting*)",
"Bash(*cli.js* schedule*)", "Bash(*creatorlens schedule*)",
"Bash(*cli.js* install*)", "Bash(*creatorlens install*)",
"Bash(*cli.js* transcripts*)", "Bash(*creatorlens transcripts*)",
"Read(~/Library/Application Support/creatorlens/**)"
],
"allow": ["Bash(<node> '<the pinned cli.js>' status --json)"]
},
"sandbox": { "filesystem": { "denyRead": ["~/Library/Application Support/creatorlens"] } }
}The command line refuses a shell an assistant started. The state-changing commands need a terminal, a typed confirmation, and no
CLAUDE_CODE_CHILD_SESSIONin the environment (Claude Code sets it in every command its tools run, from version 2.1.172). That stops an accidental or injected run, not a shell that hides on purpose.
If you turn on Claude Code's sandbox, its denyRead also stops the allowed status --json command, which reads the
data folder; the MCP status tool gives the same answer.
Commands
Command | What it does |
| shows and records your acceptance of the terms; stores the Desktop OAuth client (secret in the Keychain) |
| signs in one channel in your browser (PKCE, loopback on 127.0.0.1); you confirm the channel's name and id |
| creates a job for every report type the channel is offered (newest version, not system-managed); deletes the jobs creatorlens made; shows coverage |
| downloads new report files into the archive, refreshes your own metadata, runs the clocks |
| a LaunchAgent: daily at 07:30 and at login, running the pinned copy with an absolute node path |
| operational state only: sign-in, jobs, freshness, warnings; no audience figures, no strangers' text |
| checks everything that could stop the data; green means no check failed |
| the same read-only sandbox as the tool, printed safely for a terminal |
| the profile's log (ids and counts, redacted) |
| deletes data; |
| offers to delete the jobs, revokes at Google, deletes everything for that channel |
| copies the build into the data folder (refuses when tests fail) |
| transcript folders (inside |
| prints the |
| the MCP server over stdio (your MCP client runs it) |
State-changing commands (setup, auth, reporting enable|disable, schedule install|remove, purge, revoke,
install, transcripts add|remove) need a terminal, a typed confirmation and a shell no AI assistant started: a speed
bump against an assistant's shell, not a wall (see "Settings for the folder where you use it").
MCP tools (v0)
Tool | Returns |
| per profile: the bound channel, the sign-in and policy clocks, jobs and their newest report, freshness, schedule, warnings |
| the tables of a profile's store, each column's meaning and origin, and example queries |
| one read-only SELECT on a profile's store, in the sandbox; strangers' text wrapped |
Every tool is annotated read-only and takes profile; a call reads one channel only. Resources:
creatorlens://schema, creatorlens://glossary, creatorlens://privacy.
What no API gives
Search volume and autocomplete; YouTube Studio's Research, Trends and Inspiration tabs; Test & compare results; unique, new and returning viewers; "Stayed to watch" and "Shown in feed" for Shorts; real-time figures; clicks from YouTube to an external site; other channels' private analytics. Transcripts need a write-capable scope, so creatorlens does not read them.
Report download host
Report files are downloaded only from youtubereporting.googleapis.com. If Google ever serves them from another host,
creatorlens refuses the download, sends nothing there and says so in status and doctor. Please open an issue with
the host name (never a URL with a token in it).
Development
pnpm install --frozen-lockfile
pnpm run typecheck
pnpm test # builds, then runs node --test on test/ (unit, policy clocks on a fake clock, SQL sandbox, stdio contract)
sh scripts/gitleaks.sh gitFixtures are synthetic: channel ids start with UCzz, video ids with zz, and a test fails on anything else. The
design and every decision behind it: docs/design.md. Contributing: CONTRIBUTING.md.
Licence
MIT, see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Your YouTube channels’ private analytics for AI assistants: revenue, views, retention. Read-only.
Read-only Google Search Console and Google Analytics for AI agents.
Work with your database from AI tools: ask, export, approved changes, and scheduled jobs.
YouTube for AI agents: transcripts, comments, video stats, channel monitor, Shorts captions.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to inspect and query a MySQL database through safe, structured tools, including schema discovery and read-only queries.9104 npmMIT
- FlicenseNot gradedqualityDmaintenanceExposes a SQLite database to AI assistants with structured, read-safe access. Includes five tools for schema exploration, querying, and sampling data.-
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants like Claude to query, analyze, and summarize local SQLite e-commerce databases using natural language through 11 tools, schema resources, and pre-built analytical prompts.-
- AlicenseAqualityDmaintenanceEnables AI agents to safely interact with a SQLite shop database through schema discovery, read-only SQL queries, and pre-built analytics reports like top customers, top products, and revenue summaries.669 npmMIT