@socialmemory/mcp

Use saved X likes and bookmarks from socialmemory inside Codex, Claude Code, and Cursor.

This package covers the Agent Access path for Codex, Claude Code, and Cursor. The web app and Chrome extension are separate product surfaces that use the same socialmemory archive.

It lets local agents such as Codex, Claude Code, and Cursor:

• search a user's saved X likes and bookmarks

• refresh saved X likes and bookmarks from the local browser session

• read one saved post

• append notes to saved posts

• merge tags into saved posts

• create a socialmemory web link that opens exactly the posts returned by the agent

• check archive and sync status

Release Guard

Official package identity:

• npm package: @socialmemory/mcp

• public repo: https://github.com/kennyberg/socialmemory-mcp

• release path: GitHub workflow in .github/workflows/publish.yml

Before releasing, verify:

npm run release:guard
npm test
npm run check
npm run pack:dry-run

The package name must stay @socialmemory/mcp, and the package repository must stay https://github.com/kennyberg/socialmemory-mcp. Do not publish if the package name, repository URL, or release guard result is unexpected.

Related MCP server: Xee-mcp

Requirements

• Node.js 20 or newer

• A socialmemory account

• An active socialmemory Personal plan or trial

• Chrome, Chromium, Brave, or Edge on macOS for local X sync in this first version

• The user must be signed into X in that local browser profile before running sync

CLI Login

The package now includes two binaries:

• socialmemory is the user-facing CLI.

• socialmemory-mcp is the MCP server that Codex and Claude Code run.

Run:

npx -y --package @socialmemory/mcp socialmemory login

This starts a short login session, opens socialmemory in the browser, shows a code, and waits while the user approves the local agent. After approval, the CLI stores the credential locally without printing the token.

On macOS, the CLI stores the credential in Keychain using the security command. If Keychain is unavailable, it falls back to ~/.config/socialmemory/credentials.json with file mode 0600.

Check the local setup:

npx -y --package @socialmemory/mcp socialmemory status
npx -y --package @socialmemory/mcp socialmemory doctor

Revoke this credential on the socialmemory server and remove the local copy:

npx -y --package @socialmemory/mcp socialmemory logout

SOCIALMEMORY_AGENT_TOKEN is still supported as an advanced fallback. It takes priority over the stored local credential.

Codex Setup

The socialmemory web app generates the full command on the Agent Access page under Set up Codex.

Run the generated setup command:

npx -y --package @socialmemory/mcp@latest socialmemory setup codex --base-url https://socialmemory.dev

That one command installs socialmemory in Codex, checks supported local Chrome, Chromium, Brave, and Edge profiles for a signed-in X session, asks which profile to use when needed, opens the browser login, saves the approved credential locally, starts a full first sync when the archive is empty or has never synced, and prints the current archive status. A safely running or paused first sync can leave the library empty for a while without making installation fail. The command calls the import complete only after Sync v2 reports all_sources_complete.

If setup finds one usable X account/profile, it saves that local choice for future syncs. If it finds more than one, it asks which browser profile to use and shows each browser, profile name, Google account, and choice id. It only shows the X account when socialmemory can read it safely. In a noninteractive shell, such as CI, setup exits with exact commands you can rerun, for example:

npx -y --package @socialmemory/mcp@latest socialmemory setup codex --base-url https://socialmemory.dev --session-id chrome-profile-default

The advanced env-token fallback still works when browser login is unavailable:

codex mcp add socialmemory \
  --env SOCIALMEMORY_BASE_URL=https://socialmemory.dev \
  --env SOCIALMEMORY_AGENT_TOKEN=YOUR_TOKEN \
  -- npx -y --package @socialmemory/mcp@latest socialmemory-mcp

Restart Codex after adding the connector, then ask:

check my socialmemory status

Claude Code Setup

The socialmemory web app generates the full command on the Agent Access page under Set up Claude Code.

If you have run socialmemory login, the command can use the locally stored credential:

claude mcp add --transport stdio \
  --scope user \
  socialmemory \
  -- npx -y --package @socialmemory/mcp@latest socialmemory-mcp

The advanced env-token fallback still works:

claude mcp add --transport stdio \
  --env SOCIALMEMORY_BASE_URL=https://socialmemory.dev \
  --env SOCIALMEMORY_AGENT_TOKEN=YOUR_TOKEN \
  --scope user \
  socialmemory \
  -- npx -y --package @socialmemory/mcp socialmemory-mcp

Restart Claude Code or run /mcp after adding the connector.

Cursor Setup

The socialmemory web app generates the full command on the Agent Access page under Set up Cursor.

Run the generated setup command:

npx -y --package @socialmemory/mcp@0.4.0 socialmemory setup cursor --base-url https://socialmemory.dev

The command safely merges the socialmemory entry into Cursor's official global configuration at ~/.cursor/mcp.json. It preserves unrelated Cursor MCP entries and other top-level configuration, opens the normal browser-approved socialmemory login with the client name Cursor, and finishes with doctor and status checks. Rerunning the command keeps the same configuration instead of creating duplicates.

Environment Variables

SOCIALMEMORY_AGENT_TOKEN is optional. It is an advanced fallback and takes priority over the local stored credential.

SOCIALMEMORY_BASE_URL is optional. It defaults to https://socialmemory.dev.

Never paste the token into chat messages. Store it with the CLI, or use it only in the MCP setup command or MCP config.

CLI Commands

socialmemory login

Open the browser-based authorization flow and store the credential locally after approval.

socialmemory login --token-stdin

Read one generated agent token from stdin and store it locally. The token is not printed.

socialmemory logout

Revoke the active credential on the socialmemory server, then remove its local copy. Use socialmemory logout --local-only only when the server cannot be reached and you intentionally accept that the server credential remains active. If SOCIALMEMORY_AGENT_TOKEN is active, logout revokes that environment credential but cannot unset the shell variable and does not delete a separate Keychain/file credential hidden behind it. Unset the variable, then run logout again to revoke and remove that stored credential.

socialmemory status

Show the current credential source and archive/sync status.

socialmemory doctor

Check Node.js, credential storage, credential presence, server capabilities, and whether the selected local browser profile is signed into X. A progressively rolled-out feature is reported honestly without blocking other staging checks. Release validation must use socialmemory doctor --require-release-capabilities, which fails if any capability promised by the current MCP release is unavailable.

socialmemory setup codex

Install socialmemory in Codex, choose the local X account/profile to use for sync, run browser login, verify setup with doctor, and start or continue a full first sync. If saved posts are already usable, setup succeeds while clearly reporting that the import is still incomplete. Only a v2 run with every required source finished is called complete.

socialmemory setup cursor

Add socialmemory to Cursor's global MCP configuration without changing unrelated entries, run browser-approved login with the Cursor client name, and verify the connection with doctor and status.

socialmemory sync

Run local X sync from this machine. Options:

socialmemory sync --mode recent
socialmemory sync --mode full --force
socialmemory sync --browser brave
socialmemory sync --x-handle alex
socialmemory sync --session-id chrome-profile-default

When no --browser flag is passed, sync scans supported local browser profiles and tries to detect the active X handle in each readable profile. If setup saved an account/profile choice, sync uses that choice unless you pass --x-handle or --session-id. If there is no saved choice and multiple active X handles or browser profiles are detected, sync stops and asks you to run again with --x-handle when handles are available or --session-id when only profile labels are available.

Tools

search_saved_x

Retrieve broad candidate posts from saved X likes and bookmarks. Pass the user's original request as intent, add optional concise probes, and add one optional meaningQuery when conceptual retrieval is useful.

Search responses contain unverified candidates and transparent retrieval evidence, not a prewritten answer. The calling agent reads the candidates and decides which are direct matches, related material, or irrelevant.

list_saved_x

Enumerate exact pages from the saved-X archive by liked/bookmarked state, post-publication date, author, X bookmark folder, tag, content type, favorite state, or note state. Follow nextCursor without changing the filters until queryExhausted is true before claiming an exhaustive result.

X does not provide the time when the user pressed Like or Bookmark. Date filters use the time the X post itself was published, and every response states that limitation explicitly. Import time, sync time, and database save time are never presented as Like or Bookmark action time.

sync_x_memory

Refresh saved X likes, bookmarks, and X bookmark-folder memberships from a detected local browser session. The default mode is recent. Full sync is available only when explicitly requested.

One MCP tool call processes a bounded slice so an interrupted agent process cannot lose its place. A large archive may return in_progress; call the tool again with the same browser selection to resume the server checkpoint. Only success means every required X source reached a verified completion boundary. Rate limits, safety pauses, and partial folder failures are reported explicitly and are never presented as success.

The tool scans supported local browser profiles and syncs one readable X session at a time. If setup saved an account/profile choice, the tool uses that choice. If multiple active X handles are detected and no saved or explicit choice exists, the tool returns a needs_selection response with the detected handles; run it again with xHandle to choose one. If handles are unavailable but multiple readable browser profiles are found, run it again with the chosen sessionId. It does not select inactive accounts inside X's account switcher. To sync a different account inside the same browser profile, switch to that account in X first, then run sync again.

get_saved_x_post

Read one saved post by id.

read_saved_x_posts

Batch-read the complete safe stored context for up to 20 candidate posts before judging relevance. The response reports requested, returned, and missing counts so an agent cannot honestly claim to have read more posts than it received.

add_saved_x_note

Append a note to one saved post.

save_x_to_socialmemory

Save one supported X post or X Article only after the user explicitly asks. The tool accepts one URL plus an optional user-authored note and tags. Socialmemory validates the URL and retrieves authoritative X content through its shared Manual Add engine; the agent never submits post text, author, media, or provider payloads. Failures use the MCP error signal and must not be reported as success.

merge_saved_x_tags

Add tags to one saved post without removing existing tags.

create_socialmemory_result_set

Create a web link that opens exactly the selected saved posts in the socialmemory app.

get_socialmemory_status

Show archive counts, latest saved item time, latest sync time, and latest sync status.

Privacy Model

The sync runs on the user's own machine. It reads the local browser session so it can see the user's own X likes and bookmarks, then uploads normalized saved-post data to the user's private socialmemory cloud archive.

The selected browser profile and X account stay local. Socialmemory uploads normalized saved-post data and non-sensitive run/version counters, but it does not attach the originating browser profile, X handle, X user id, or local run metadata to each saved post. Raw cookies and local browser paths are never uploaded.

The MCP connector does not print the private token in tool responses or logs.

Troubleshooting

If sync says it cannot find the local X session:

1. Open Chrome, Chromium, Brave, or Edge on the same Mac.

2. Sign into X.

3. Open the X bookmarks page once.

4. Run sync_x_memory again.

If sync reports multiple active X handles:

1. Pick the handle you want to import.

2. Run sync_x_memory again with xHandle, or run socialmemory sync --x-handle HANDLE.

3. Sync other X handles one at a time.

If search works but sync is skipped:

The socialmemory server is protecting the account from repeated refreshes. Wait until the cooldown time shown in the response, then try again.

If meaning search fails:

The socialmemory server may not have Meaning search configured or ready. Continue with the word-retrieved candidates and explain the reduced coverage when it affects the answer.