creator-analytics

Documentation · MCP setup · Report a bug · Request a feature

Creator Analytics is a self-hosted archive for creators' YouTube, TikTok, Instagram and LinkedIn analytics. It imports
the platforms' own CSV and XLSX exports into PostgreSQL, tells you which history each platform is about to delete, and
records where every number came from. A built-in MCP server lets AI clients such as
Claude and Codex read and update the same data, through the same business logic as the web app.

[!WARNING]
No authentication. Creator Analytics is a single-user app meant to run on your own machine. Anyone who can reach
the API can read and delete everything. See SECURITY.md.

UI preview

Screenshots of the web app running on the invented demo data from backend/scripts/seed_demo.py.

Dashboard: totals, metrics about to expire, performance chart with post markers	Posts: every post across platforms, and what worked per brief field
Post: numbers against your typical post, caption, versioned brief	Post editor: post fields and the content brief, section by section
Import: exact dry run of an export before anything is saved	Metrics: how long each platform keeps a metric and where to export it
Calendar: published and planned posts on every platform	Earnings: revenue by source and period, one list per currency
Accounts: add, edit and delete social accounts	Data: browse and edit any table, read any view

Why

Creators' numbers are spread across four dashboards that each measure things differently, and every platform deletes
history on its own schedule: some daily metrics are only available for a limited window, after which the detail is gone
for good. Exports exist, but a folder of CSV files is hard to compare, query or trust later.

Creator Analytics keeps that history in a PostgreSQL database you own. You export from the platforms, drop the files in,
and the app stores every value as a dated fact, linked to the export it came from. Nothing is scraped and nothing leaves
your machine. Because the data is yours and in a standard database, you can query it, back it up, or hand it to an AI
agent without depending on any platform staying the same.

Features

Centralized analytics

• YouTube, TikTok, Instagram and LinkedIn accounts in one dashboard: followers, views and impressions, engagement, posts.
• Performance chart per account and metric, with markers for published posts.
• Audience breakdowns and inferred unfollows from follower-list snapshots.
• Earnings by source and period, with currencies kept separate.

History preservation

• A catalogue of every platform metric with how long the platform keeps it and where to export it.
• An "Expiring soon" view of what each account has saved and how many days are left.
• Provenance on every value: which import or sync saved it, from which file (with its SHA-256).

Imports

• Platform CSV exports (one row per post or one row per date) and the LinkedIn analytics .xlsx.
• Columns matched to metrics by key or by the label the platform uses.
• Exact dry-run preview, and a warning when the same file was already imported.

Content management

• Posts across platforms, searchable and sortable, with a full-screen editor.
• Versioned content briefs: topic, format, hook, script, editing and copy behind each post.
• "What worked": average views or engagement rate per brief field.
• Experiments: plan a post with a hypothesis, then compare it with your typical post and record a verdict.
• Content calendar of published and planned posts.
• A generic data explorer to create, edit and delete rows in any table.

AI integration

• An MCP server with 14 tools and one prompt, sharing the service layer with the REST API.
• Agent-drafted content briefs, flagged for your review in the app.

AI and MCP integration

The Model Context Protocol is an open standard that lets AI clients call tools
provided by other programs. Creator Analytics ships an MCP server (creator-mcp) so an agent can work with your
analytics directly instead of you copying numbers into a chat.

The server runs locally over stdio: your AI client starts it as a subprocess, and it connects to your database. Every
tool call is one transaction that goes through the same services as the REST API, so an agent gets the same validation,
upsert rules and provenance records as the web app.

Supported clients

Configuration for each is in the MCP setup guide. Other stdio MCP clients should work but
have not been tested.

Available tools

The draft_briefs prompt guides an agent through drafting briefs for every post that has none. Parameters and details
are in the MCP setup guide.

Example requests

• "Compare my average views per post on YouTube and TikTok over the last three months."
• "Which posts had the highest engagement rate this year, and what hook did they use?"
• "Show my daily LinkedIn impressions for October."
• "What do I need to export this week before the platforms delete it?"
• "Import ~/Downloads/Content 2026-11-01.csv into my YouTube account."
• "Draft briefs for my new posts." (/mcp__creator-analytics__draft_briefs in Claude Code)

Architecture

flowchart LR
    browser[Web browser] --> web["Web app<br/>TanStack Start"]
    web -- "REST /api/v1" --> api["REST API<br/>FastAPI"]
    agent["AI client<br/>Claude · Codex"] -- "MCP over stdio" --> mcp["MCP server<br/>creator-mcp"]
    exports[/"Platform exports<br/>CSV · .xlsx"/] --> api
    exports --> mcp
    api --> svc["Service layer<br/>imports · syncs · dashboard · tables"]
    mcp --> svc
    svc --> db[("PostgreSQL 17")]

The web app talks only to the REST API. The REST API and the MCP server are two thin entry points in the same Python
package and call the same service layer, which owns all business logic and writes to PostgreSQL. There are no background
jobs and no connections to the platforms. Details: system overview.

Tech stack

Getting started

Prerequisites

• Docker with Compose (for PostgreSQL)
• uv (installs Python 3.12+ if needed)
• Node.js 22.18 or newer

Installation

git clone https://github.com/BenAbdou1001/creator-analytics.git
cd creator-analytics
cd backend && uv sync && cd ..
cd web && npm install && cd ..

Environment variables

Every variable has a default that works with the setup below, so this step is optional.

Copy backend/.env.example and web/.env.example to start. See the configuration guide.

Database setup

docker compose up -d                           # PostgreSQL 17 on 127.0.0.1:5433
cd backend && uv run alembic upgrade head      # schema, views and the metric catalogue

Running locally

cd backend && uv run fastapi dev main.py --port 8000   # API, docs at http://localhost:8000/docs

In a second terminal:

cd web && npm run dev                                  # http://localhost:3000

To try the app with invented data first, see demo data.

Docker

docker-compose.yml runs PostgreSQL only. The backend and web app run on your machine with uv and npm; there are
no container images for them yet.

Tests

cd backend && uv run pytest                             # uses its own creator_test database
cd web && npm run typecheck && npm test && npm run build

Documentation

Roadmap

Done

• Multi-platform dashboard, metric catalogue with retention limits, and expiry tracking
• CSV and LinkedIn .xlsx imports with dry-run preview and provenance
• REST API and MCP server on a shared service layer
• Content briefs, agent-drafted briefs, experiments, "What worked" and the content calendar

Planned

• Nothing is committed yet. Ideas and requests are tracked in issues.

Known limitations

• No authentication; single user, local use only.
• No container images for the backend and web app.
• The MCP server supports the stdio transport only.

Contributing

Bug reports, feature requests, documentation improvements and code are welcome. Read
CONTRIBUTING.md for the development setup and conventions, and follow the
Code of Conduct.

Security

The app has no authentication by design and must stay on your own machine. To report a vulnerability, use private
reporting as described in SECURITY.md.

License

MIT © 2026 Benassloun Abdallah.

The bundled fonts, Plus Jakarta Sans and Noto Sans Arabic, are under the SIL Open Font License. Platform names and marks
belong to their owners; this project is not affiliated with YouTube, TikTok, Instagram or LinkedIn.

Acknowledgements

Built on FastAPI, TanStack, shadcn/ui,
SQLAlchemy, Alembic, the
MCP Python SDK and uv. The backend
layout follows fastapi-best-architecture.