# Ilo > ilo lets your agent research your 𝕏 audience, track the content that works, and tell you what to publish next. - **Type:** MCP server - **Install:** `agentstack add mcp-iannuttall-ilo` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [iannuttall](https://agentstack.voostack.com/s/iannuttall) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [iannuttall](https://github.com/iannuttall) - **Source:** https://github.com/iannuttall/ilo - **Website:** https://ilo.so ## Install ```sh agentstack add mcp-iannuttall-ilo ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About ilo Local X research and publishing for people and AI agents. Search public audiences, monitor replies and articles, draft from evidence, and publish after review. Get started · Documentation · Publishing accounts · Audience research · Following search · Article monitoring · npm · Questions · Privacy · Security · License · Agent notes ilo gives your agent public X evidence it can inspect before it tells you what to publish. Search follower profiles and the people an account follows, keep native X Articles in a local full-text index, collect focused replies, and turn the useful findings into drafts. The CLI, local MCP server, agent skill, and TypeScript package call the same core implementation. Drafts, monitor state, article text, schedules, and publish attempts stay in your local SQLite database. Publishing always stops for explicit confirmation. ## Who this is for - People growing an X account who want research, reply triage, drafts, and publishing in one local workflow. - Coding agents get inspectable public evidence through MCP instead of working from screenshots or generic social media advice. - Consultants, social teams, and developers can research public accounts or embed the same typed functions in their own tools. ## Quick start ilo requires Node 22.19 or newer. ```sh npm i -g iloso ilo start ``` `ilo start` asks whether you want to publish through Typefully or directly through your own X developer app. For Typefully, create a v2 API key under **Settings → API** and paste it into the hidden prompt. ilo adds every accessible Typefully social set with an X profile. For direct X, create a Native App with OAuth 2.0 read and write access, then register this callback exactly: ```txt http://127.0.0.1:8976/callback ``` Copy the OAuth 2.0 Client ID from the app's **Keys and tokens** page. Native Apps use PKCE and do not need a client secret. ilo opens the browser sign-in. Typefully API keys and X OAuth tokens stay in your operating system keychain. List or switch between every connected X publishing account: ```sh ilo accounts list ilo accounts use ``` Run `ilo --help` to see the main surface: ```txt Local-first social publishing for people and AI agents USAGE ilo start|accounts|x|post|drafts|scheduler|mcp|skill COMMANDS start Connect Typefully or your own X developer app accounts Connect and switch between X publishing accounts x Research and manage X accounts post Publish one post or reply to X drafts Create, list, schedule, and publish local drafts scheduler Run scheduled local drafts mcp Run the local stdio MCP server skill Inspect or install the packaged ilo agent skill ``` The default publishing account's handle becomes the local namespace for article and inbox monitors. Research commands fetch public X data and keep the results local. Public follower research can run with no publishing connection. Commands that need a research namespace also accept an explicit handle. The [publishing accounts guide](https://ilo.so/docs/accounts) explains Typefully, direct X, multiple profiles, account aliases, and why drafts stay bound to their original account. ## What you can do - Search imported follower names, handles, bios, and locations with SQLite FTS5, including evidence-backed current, former, and unclear employer counts. - Search the complete public profiles an account follows, with snapshot coverage, 24-hour freshness, JSON, CSV, and complete stored profile lookup. - Native X Articles from selected writers become a local full-text library that the CLI or an agent can search later. - Focused X searches feed a deduplicated reply inbox with public post, author, engagement, and relationship evidence. - Draft top-level posts or replies with up to four JPEG, PNG, or WebP images and optional alt text. - Schedules accept exact timestamps or phrases such as `tomorrow at 9am`. - MCP and TypeScript callers use the same local data and confirmation rules as the terminal. ## Research public followers Import a bounded sample, continue a full resumable sync, or let a large import run as a detached local process: ```sh ilo x followers sync adamwathan --pages 20 ilo x followers sync adamwathan --all ilo x followers sync adamwathan --background ilo x followers status adamwathan ``` Search the saved profiles once the index has data: ```sh ilo x followers search adamwathan \ --query "works at cursor|vercel|sentry" ``` Current matches are listed by default. Counts still show current, former, and unclear classifications, and every listed profile includes the public bio used as evidence. Add the noisier groups only when you need to inspect them: ```sh ilo x followers search adamwathan \ --query "works at cursor|vercel|sentry" \ --include-former \ --include-unclear ``` Search returns every selected match unless you pass `--limit`. Export the same profiles and import coverage to CSV with `--csv ./matches.csv`. Check the coverage first because an unfinished public import cannot support a complete count. The [audience research guide](https://ilo.so/docs/audience-research) covers background progress, complete profile records, classification limits, local MCP tools, TypeScript functions, terminal output, and CSV fields. ## Search the people an account follows Build a fresh local snapshot of your own following list, or name another public account explicitly: ```sh ilo x following sync --all ilo x following sync adamwathan --all ilo x following status adamwathan ``` An omitted handle uses the default publishing account's X handle as the local research namespace. A bounded sync reads 20 pages by default and resumes when you run it again. `--all` continues until the available list ends, or until the saved profiles match X's reported total and repeated pages add nothing new. Running sync after a completed import starts a fresh snapshot, while `--restart` discards an unfinished cursor. Search the saved names, handles, bios, locations, and handle aliases locally: ```sh ilo x following search adamwathan \ --query "building browser tools" ``` Search uses SQLite FTS5, so concrete profile words work better than abstract semantic questions. It returns every match unless you pass `--limit`. Each result includes the public bio or location evidence, and the coverage says how many complete profiles are searchable, whether the import finished, and whether the snapshot is more than 24 hours old. Export every match or inspect one complete stored profile: ```sh ilo x following search adamwathan \ --query "building browser tools" \ --csv ./browser-builders.csv ilo x following profile browser_builder \ --account adamwathan \ --json ``` The [following search guide](https://ilo.so/docs/following-search) documents sync and refresh behaviour, every CLI command, MCP tool, TypeScript function, JSON field, CSV column, freshness rule, and current evidence limits. ## Keep native X Articles searchable Choose the writers worth keeping, refresh their public article timelines, and search the saved full text: ```sh ilo x articles add swyx ilo x articles add karpathy ilo x articles refresh ilo x articles search --query "browser tools" ilo x articles show ``` ilo fetches the complete public body for each new native X Article and stores the timeline cursor locally. If older history remains, the next refresh continues from that cursor. Search has no hidden result limit and makes no network request after the articles are saved. This monitors native X Articles. It does not collect every external link or normal post a handle shares. Search uses SQLite FTS5 rather than embeddings, so concrete names and words work better than abstract semantic questions. The [article monitoring guide](https://ilo.so/docs/articles) documents every CLI command, MCP tool, TypeScript function, JSON field, history state, and current limit. ## Build a local reply inbox Save focused X searches and refresh them when you want new posts: ```sh ilo x monitors add "ilo mentions" \ --query '"ilo" OR "ilo.so" -is:retweet' ilo x inbox refresh ilo x inbox list --verified ``` Import follower and following profiles when relationship filters matter: ```sh ilo x following sync --all ilo x followers sync --all ilo x inbox list --i-follow ilo x inbox list --follows-me ``` Relationship values stay unknown until the relevant local import has enough coverage to answer. ilo does not turn missing data into `false`. The following import is also the searchable profile index described in the [following search guide](https://ilo.so/docs/following-search). Inspect a post before drafting a reply: ```sh ilo x inbox show ilo x inbox draft --text "Reply to review" ``` Drafting saves the reply target and marks the inbox item as read. Nothing is published until the normal confirmation step. ## Draft, schedule, and publish Publish one reviewed post directly: ```sh ilo post --text "Hello from ilo" ilo post \ --reply-to https://x.com/example/status/123 \ --text "A reply from ilo" ilo post \ --text "Weekly signups" \ --image ./chart.png \ --alt "Bar chart of weekly signups by source" ``` Save an idea when it is not ready yet: ```sh ilo drafts create --text "Post this tomorrow" ilo drafts list ilo drafts schedule --at "tomorrow at 9am" ilo drafts publish ``` Run due schedules once or keep a local watcher open: ```sh ilo scheduler run ilo scheduler watch --interval 60 ``` Interactive publishing shows the exact text, top-level or reply destination, and images before asking for confirmation. Use `--yes` only after another caller has already confirmed that exact action. ## Use ilo with AI agents Install the packaged skill so a coding agent knows the workflow and publishing rules: ```sh ilo skill install ``` Add the local stdio MCP server to Claude Code or Codex: ```sh claude mcp add ilo -- iloso mcp serve codex mcp add ilo -- iloso mcp serve ``` Config-based clients can use the same command: ```json { "mcpServers": { "ilo": { "command": "iloso", "args": ["mcp", "serve"] } } } ``` The client starts the server as a child process when it needs a tool. The server uses stdin and stdout, opens no network port, and reads the same local database as the CLI. Keep research and publication as separate agent steps: ```txt Search my saved X articles for browser tools. Show the strongest evidence and any missing history. Do not draft or publish anything. ``` ```txt Create a local reply draft for this inbox item. Show me the exact text and reply target, then stop for review. ``` Publishing tools require `confirm: true` for the exact action. Creating a draft, searching local data, or refreshing a public monitor never publishes. The [local MCP guide](https://ilo.so/docs/mcp) lists the tools and setup for Claude, Codex, Cursor, and other compatible clients. ## Use ilo as a TypeScript package Install `iloso` in a Node 22.19 or newer project: ```sh npm install iloso ``` Call the same core functions used by the CLI and MCP server: ```ts import { createDraft, createXArticleMonitor, getXArticle, refreshXArticleMonitor, scheduleDraft, searchXArticles, } from 'iloso' const monitor = createXArticleMonitor({ accountHandle: 'ilodotso', sourceHandle: 'swyx', }) await refreshXArticleMonitor({ id: monitor.id, maxPages: 3 }) const matches = searchXArticles({ accountHandle: 'ilodotso', query: 'browser tools', }) if (matches[0]) { const article = getXArticle({ accountHandle: 'ilodotso', identifier: matches[0].postId, }) const draft = await createDraft(`A useful idea from ${article.title}`) await scheduleDraft(draft.id, 'tomorrow at 9am') } ``` The root package exports follower and following sync and search functions, complete stored profile lookup, article monitoring, reply inbox actions, publishing accounts, Typefully setup, local drafts, schedules, static image helpers, X OAuth, public X helpers, configuration, and storage paths. The package is pre-1.0, so pin the version when another application depends on exact function signatures. The [TypeScript guide](https://ilo.so/docs/typescript) has complete examples for research, drafting, publishing, and embedding the MCP server. ## Know where the data goes ilo keeps non-secret configuration under `~/.config/ilo` and local working data in `~/.config/ilo/ilo.sqlite`. Typefully API keys, X OAuth tokens, and the optional X client secret use your operating system keychain. There is no hosted ilo account or draft database. The CLI makes the network requests required to connect X, publish approved posts, and retrieve the public research data you request. Set `ILO_HOME` when a script or test needs an isolated local directory. Back up `ilo.sqlite` if your drafts, monitor history, or saved research matter. Do not copy keychain exports or OAuth tokens into a repository, issue, or shell script. ## Understand the current limits - X is the only publishing network today. It can publish through Typefully or direct X OAuth. Bluesky and LinkedIn publishing are planned. - Typefully is a publishing route in the current release. Research works independently of the publishing connection, and Typefully analytics ingestion is planned for later. - Article monitors only collect native X Articles and refresh on demand. - Follower employer results classify claims in public bios. They do not verify someone's employment. - The public report library explains useful performance analyses, but automated local account-history reports have not shipped yet. - Images can be JPEG, PNG, or WebP. Animated GIF and video uploads are still planned. Public data can be incomplete, delayed, or unavailable. ilo keeps coverage and fetch errors visible so an agent can describe what the result supports. ## Common questions ### Do I need an X developer app? No. Connect a personal Typefully v2 API key when your X profiles already live there. Direct publishing through X still needs your own X Native App. Public follower research does not require either connection. Article and inbox commands can use an explicit handle as their local namespace. ### Can I use several X accounts? Yes. `ilo accounts add typefully` imports every accessible X social set, and `ilo accounts add x` connects another direct X profile. Use `ilo accounts use` to change the default or pass `--account` for one action. Existing drafts stay on the account they were created for. ### Will ilo post without asking me? No. Interactive commands ask for confirmation, and MCP publishing tools require `confirm: true`. A scheduled draft also needs explicit authorization before a scheduler can publish it. ### Is follower, following, or article search semantic? No. All three use local SQLite FTS5. That keeps search fast, inspectable, and free, but concrete words, handles, companies, and phrases work better than questions that depend on synonyms or inferred meaning. ### Does my data stay on my machine? Drafts, schedules, monitor state, imported public data, and publish attempts stay in local SQLite. Secrets stay in the keychain. ilo only sends the network requests needed for the X and public-data actions you explicitly run. ### What does ilo cost? The package is free and open source under MIT. Your own X API access, provider limits, and normal network costs still apply. ## Documentation and support - [Getting started](https://ilo.so/docs/start) - [Publishing accounts](https://ilo.so/docs/accounts) - [CLI commands](https://ilo.so/docs/cli) - [Following search](https://ilo.so/docs/following-search) - [Article monitoring](https://ilo.so/docs/articles) - [Local MCP and agents](https://ilo.so/docs/mcp) - [TypeScript package](https://ilo.so/docs/typescript) - [X report library](https://ilo.so/reports) - [Privacy policy](PRIVACY.md) - [Security p … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [iannuttall](https://github.com/iannuttall) - **Source:** [iannuttall/ilo](https://github.com/iannuttall/ilo) - **License:** MIT - **Homepage:** https://ilo.so Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-iannuttall-ilo - Seller: https://agentstack.voostack.com/s/iannuttall - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.