# birdclaw

> Local SQLite archive of your Twitter/X history with a web app, CLI and MCP server

- Repository: https://github.com/steipete/birdclaw
- Category: Productivity & personal
- Stars: 1,669 · Forks: 156 · Language: TypeScript · License: MIT
- Experience: Some experience
- Page: https://ir.adyog.com/repos/steipete/birdclaw/

Your Twitter/X history is hard to search and hard to hand to an AI agent. Birdclaw takes the archive zip you can download from X and loads it into SQLite on your own machine. Tweets, DMs, likes, bookmarks, profiles, media and follow edges all end up in the same tables.

Search uses SQLite's FTS5 full-text index, so local reads are fast and make no network calls. You can use it through a web app on localhost, a CLI with JSON output, or an optional MCP server that exposes cached tweet search and thread lookup as read-only tools.

Live data is opt-in. When you ask, it syncs your timeline or bookmarks through xurl or an existing bird install. The README says it is for people who want their own history without a cloud backend, and that it is not affiliated with X Corp.

## What it does

- **Archive import**: Imports tweets, DMs, likes, bookmarks, profiles, media and follow edges from a Twitter/X archive zip. Imports are idempotent, so re-running them is safe.
- **Local full-text search**: SQLite is the main store, with FTS5 search over tweets and DMs. Data lives under ~/.birdclaw, or wherever BIRDCLAW_HOME points.
- **Web app and CLI**: The web app covers home, mentions, saved posts, DMs, inbox, moderation and network views. The CLI offers search, sync, moderation and JSON output.
- **Explicit live sync**: Syncs timeline and bookmarks through xurl or bird only when you run the command. Live writes can be turned off with BIRDCLAW_DISABLE_LIVE_WRITES=1.
- **Read-only MCP and backups**: The MCP endpoint stays off until you configure a token and public URL. Backups are deterministic JSONL shards that round-trip through Git.

## What you could build

- Search years of your own tweets and DMs offline from the command line.
- Give an AI agent read-only access to your tweet history through the MCP server.
- Browse your bookmarks and likes in a local web app.
- Back up your Twitter/X data as JSONL shards kept in a Git repository.
- Serve a read-only archive site by setting BIRDCLAW_DEPLOYMENT_READ_ONLY=1.

## Who it's for

Suits developers comfortable with a terminal who want their Twitter/X data local; you should have requested your X archive and have a recent Node.js (26.5.1 or later) or Homebrew.

## Get started

Install with Homebrew (or npm install -g birdclaw), then create the demo database and start the web app at http://localhost:3000. To use your own data, run birdclaw import archive with your X archive zip.

```
brew install steipete/tap/birdclaw
```
```
birdclaw init --demo
```
```
birdclaw serve
```

Tags: twitter, sqlite, mcp, cli, local-first