PIL
Query your personal Instagram library: search posts, fetch full post details, list folders and tags, and view library stats.
search_posts – Full-text search over captions and deep-read knowledge (summaries, key points, how-tos) with optional folder/tag filters and result limit (1–50).
get_post – Retrieve a single post's complete record: metadata, summary, key points, how-to steps, links, folders, and tags.
list_folders – List all saved-post collections with indexed vs. reported counts.
list_tags – List tags by usage, most-used first (with optional limit).
library_stats – Get totals and deep-read coverage per field for the entire library.
Provides read-only tools to search and retrieve deep-read knowledge from your local Personal Instagram Library, including saved posts, collections, tags, summaries, key points, how-to steps, and extracted links.
Your Instagram saved posts — deep-read by AI, searchable forever, on your machine.
Get started · How it works · Other AI tools · What's inside
mcp-name: io.github.pjpoulose/pil
Get PIL in 3 steps
1. Copy-paste this into Muse:
Clone https://github.com/pjpoulose/PIL into your workspace and follow its SKILL.md to set up my Personal Instagram Library. Work through it step by step — install, build the library from my saved posts, and hand me the installable app.2. When it asks, link your Instagram (one tap in your browser).
3. Download the app file it sends you → unzip → double-click Start PIL → click Install.
That's the whole thing. Your Muse does the setup, the reading, and the building. Want it on your phone too? Just ask your Muse — it handles that as well.
Mac / Linux:
curl -fsSL https://raw.githubusercontent.com/pjpoulose/PIL/master/bootstrap.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/pjpoulose/PIL/master/bootstrap.ps1 | iexThen build your library with the commands in Manual setup.
Every day you save posts you'll never find again. PIL (Personal Instagram Library) turns your Instagram saved collection into a private knowledge base on your own machine: every post deep-read by vision AI — narrative summaries, key points, how-to steps, links it discusses, automatic tags — searchable in seconds and queryable live from your AI coding tools.
Code is shared, data stays home. This repo contains only code, the database schema, config examples, and docs. Your saved posts, captions, and account details never leave your computer — ingestion, extraction, search, and the MCP server all run locally. A
.gitignoreblocks databases, configs, and exports from ever being committed.

Concept mockup with sample data — your library looks like this, with your posts.

Want your Claude, Codex, or Cursor to access this?
Connect the read-only MCP server and your other AI tools can query your library live — always current, nothing to re-upload. Your Muse can wire it up for you. How to connect →

How it works
flowchart LR
A["Instagram saved posts"] -->|"ingest"| B["Local SQLite on your machine"]
B -->|"vision AI<br/>deep read"| C["Summaries, key points, how-tos, links, tags"]
C --> D["Query two ways"]
D --> E["MCP server — Cursor, Claude Code, Desktop"]
D --> F["Static JSON export — any AI tool"]Related MCP server: bookmarks-mcp

Manual setup (do it yourself)
Prerequisites: python3 (3.11+) and instagram-cli with your Instagram
account linked (run instagram-cli accounts — it must list your account).
The one-line installer at the top of this page handles all of this for you.
# 1a. Install from PyPI (recommended — no clone needed)
pip install personal-instagram-library
# gives you: pil-mcp pil-ingest pil-extract pil-tag
# pil-export-web pil-export-html pil-export-pwa pil-publish-pwa
# 1b. Or get the code
git clone https://github.com/pjpoulose/PIL.git pil && cd pil
# 2. Configure (your data lives in data_dir, default ~/.local/share/pil)
cp pil.config.example.json ~/.config/pil/pil.config.json
# edit it: set account_id to your user_fbid from `instagram-cli accounts`
# 3. MCP server dependency
pip install "mcp<2"Build your library (each step is resume-safe — re-run any time):
cd bin
python3 ingest_saved.py # collections + saved posts
python3 extract_content.py # vision-AI deep read (batches of 25)
python3 tag_all.py # programmatic tags for untagged posts
python3 export_web.py # static JSON export -> <data_dir>/web_data.json
python3 export_html.py # searchable HTML dashboard -> <data_dir>/pil_library.html
python3 export_pwa.py # installable PWA bundle -> <data_dir>/pwa/Ask it anything — via the live MCP server or the static export:
python3 bin/mcp_server.py # read-only, stdio — Ctrl-C to stopThat's it. Re-run ingest_saved.py whenever you save new posts; extract_content.py
only processes posts it hasn't seen yet.
The app: ask your Muse to build and send it — see Your library as an app.

Why not just scroll your saved tab?
Instagram saved tab | PIL | |
Find a post from 2 years ago | Scroll endlessly | Full-text search in seconds |
Remember what a post actually said | Rewatch / reread it | AI summary, key points, how-to |
Links a post mentioned | Gone unless you saved them | Extracted and clickable |
Use it inside your AI tools | Screenshots and retyping | MCP server or JSON export |
Where your data lives | Meta's servers | Your machine, SQLite |

Ask your library from other AI tools
Live (recommended): MCP. Point any MCP-compatible assistant at the read-only server and every question reads your current database — always up to date, no exports, no re-uploads:
python3 /path/to/pil/bin/mcp_server.py # stdio; Ctrl-C to stopWiring for Claude Code, Claude Desktop, and Cursor: references/mcp_clients.md. Any MCP-compatible client works — and your Muse can connect it for you if you'd rather not touch configs. Available tools:
Tool | What it does |
| Text search over captions + deep-read knowledge, with optional folder/tag filters |
| Full record for one post: summary, key points, how-to, links, folders, tags |
| Your saved collections with indexed counts |
| Tags by usage |
| Totals + deep-read coverage per field |
The server opens the database with SQLite mode=ro and exposes SELECT-only
tools — it cannot modify your library. (Attack-tested: SQL injection, write
attempts, and limit abuse all verified blocked.)
Snapshot: file upload. Ask your Muse to send you the web_data.json file
(built with export_web.py): every post with its deep-read knowledge in one
file. Attach it to any AI chat (Claude, ChatGPT, …) and ask questions like any
document. It's frozen at export time — a snapshot, not a live connection — so
ask your Muse for a fresh copy after you save new posts.
Directly (advanced). The database is plain SQLite at <data_dir>/pil.sqlite
(schema in schema.sql). Open it read-only with any SQLite tool.
These files hold your personal Instagram data — keep them on your own machine and only share them with tools you trust.

Your library as an app
Your Muse builds the app for you and sends it to you — for your computer and your phone. Just ask:
"Send me my PIL app" — download the file it sends you, unzip, double-click Start PIL, click Install. It lives on your computer like any other app and works fully offline.
"Put PIL on my phone" — it handles the publishing and gives you a QR code to scan. Tap Install (Android) or Share → Add to Home Screen (iPhone).
No commands, no hosting setup, no terminal — your Muse takes care of all of it.
Signal Deck — the visual dashboard (v1.2.0)
Prefer exploring over querying? The Signal Deck (dashboard/) builds a
self-contained HTML dashboard from your local PIL database: a topic-ring hero
over everything you saved, search → synthesis (The Brief), a sources rail, a
sticky index, and a full archive grid. One file, works offline, your data
never leaves your machine.
cd dashboard
PIL_DB=~/.local/share/pil/pil.sqlite python3 build-signal.py
# open pil-signal-deck.html in Chrome/SafariSee dashboard/README.md for details, PWA notes, and the QA suite.

What's inside
pil/
├── assets/logo.svg # the seal above
├── SKILL.md # skill definition (for Muse)
├── README.md # this file
├── LICENSE # MIT
├── schema.sql # the five tables: folders, posts, post_folders, knowledge, tags
├── pil.config.example.json # copy to pil.config.json and set your account_id
├── bootstrap.sh # one-line installer for Mac/Linux
├── bootstrap.ps1 # one-line installer for Windows
├── bin/
│ ├── pil_common.py # config resolution + DB helpers
│ ├── ingest_saved.py # step 1: ingest (resume-safe)
│ ├── extract_content.py # step 2: vision-AI extraction (resume-safe)
│ ├── tag_all.py # step 3: tagging
│ ├── export_web.py # step 4: static export
│ ├── export_html.py # step 5: self-contained HTML dashboard
│ ├── export_pwa.py # step 6: installable PWA bundle (manifest + SW + icons)
│ ├── publish_pwa.py # step 7: publish PWA to your own host for phone install
│ └── mcp_server.py # read-only MCP server (stdio)
└── references/
└── mcp_clients.md # Cursor / Claude Code / Claude Desktop wiring
FAQ
Do I need to know how to code? No. Copy-paste the prompt at the top of this page into Muse — it does everything with you. The only things you'll do yourself are linking Instagram (one tap in your browser) and downloading the app file it sends you.
Where does my Instagram data go? Nowhere. Code is shared, data stays home: your saved posts, captions, and account details never leave your computer. Nothing is uploaded to us — there is no "us"; there's no server, no account, no cloud.
Does it cost anything? PIL is free and open-source (MIT). There is no subscription and no account to create. The AI deep-read step runs through your own Instagram/AI setup.
Does the app work offline? Yes. Once installed, the desktop and phone apps run fully offline — search, rooms, tags, and answers all work without internet.
Which phones and computers? Windows, Mac, and Linux for the desktop app; iPhone and Android for the phone app. On Android, tap Install app in Chrome; on iPhone, use Safari's Share → Add to Home Screen.
I saved new posts — how do I add them? Just tell your Muse "I saved new posts." It fetches and deep-reads only the new ones, then refreshes your app and files.
Can I share my library with someone? Your library is files on your machine — you can copy them to someone else's computer, but they contain your personal Instagram data. Treat them like anything private: don't publish or upload them anywhere public.
Something failed — what now?
Tell your Muse what you saw — it can diagnose and fix it directly. (Running
the manual setup below? Re-run the installer — it's safe to run any number of
times — and check python3 --version is 3.11+.)

Troubleshooting
Something wrong? Tell your Muse what happened — it can diagnose and fix most issues itself.
Running the manual setup yourself?
PIL account_id is not configured→ copy the example config and setaccount_idto youruser_fbidfrominstagram-cli accounts.Extraction is slow on huge libraries — it's resume-safe; just re-run it.
429rate limits are handled with backoff inside the scripts.The MCP server needs
mcp<2in the Python that runs it (2.x renamed the API).

Contributing
PRs and issues welcome — better extraction prompts, new query clients, new export formats. Fork it, ship it, make it yours. If it saved you from the endless scroll, a star helps others find it.

License
MIT. Built by Paul Poulose.
Available Tools
5 toolsget_postB
Return everything PIL knows about one post: metadata, deep-read knowledge (summary, key_points, howto, links), folders, and tags.
Inputs: post_id (required).
library_statsC
Totals for the library plus deep-read coverage per field.
Inputs: no named parameters.
list_foldersA
List the user's saved-post collections (rooms). item_count is the
count Instagram reports; mapped_posts is how many are actually indexed.
Inputs: no named parameters.
list_tagsC
List tags by usage, most-used first.
Inputs: limit.
search_postsA
Search the library. Matches query text against captions and deep-read
knowledge (summaries, key points, how-to). Optionally restrict to one
folder (collection id or folder name) and/or one tag. Returns up to limit
matches (1-50) as compact cards with a has_knowledge flag.
Inputs: query (required), tag, limit, folder.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a clearly distinct purpose: single-post retrieval (get_post), collection listing (list_folders), tag listing (list_tags), aggregate metrics (library_stats), and query-based retrieval (search_posts). There is no meaningful overlap between them, so an agent can select the right tool unambiguously.
Four tools follow a clean verb_noun pattern (get_post, list_folders, list_tags, search_posts). library_stats breaks the pattern by being noun-only with no verb, a minor deviation that doesn't hurt readability.
Five tools is well-scoped for a read/browse library server. Each tool earns its place, covering retrieval, browsing by folder/tag, search, and stats without redundancy.
The read-side surface is solid: single-item lookup, folder/tag enumeration, search, and stats cover the main workflows. Minor gaps exist—no plain list-all-posts or folder-contents tool—but search_posts with folder/tag filters largely compensates.
Maintenance
Related MCP Connectors
Social media MCP server: your Instagram, TikTok, YouTube, LinkedIn and Threads history for your AI.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Hosted Instagram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Instagram data over MCP: profiles, posts, reels, stories, highlights and search as JSON
Related MCP Servers
- AlicenseNot gradedqualityDmaintenancePrivacy-first personal knowledge database for your AI that ingests data exports (Google Takeout first) and exposes them via MCP tools like search and list items. Runs locally with no cloud or telemetry.MIT
- AlicenseAqualityCmaintenanceA local, read-only MCP server that makes bookmarks from browsers, read-later apps, and export files accessible to AI assistants, enabling search, triage, and summarization without sending data anywhere.870 npm1MIT
- AlicenseNot gradedqualityCmaintenanceTurns likes, bookmarks, and saved links into persistent project-aware memory, enabling AI agents to search, import, and process personal content through a local SQLite-backed MCP server.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceExposes a locally built, searchable index of your saved Instagram reels — AI summaries, key points, transcripts, categories, and every extracted tool, place, product, and link — to any AI assistant over MCP. Enables chat-based search and retrieval across the whole collection without leaving the conversation.1Apache 2.0