Truth Social MCP

A local Python MCP 2.x server for explicitly authorized Truth Social access. It keeps model-facing tools separate from credential setup, defaults to read-only, and treats all social content as untrusted external data.

Current safety boundary

Truth Social's current Terms of Service prohibit automated/non-human access and data extraction unless separately authorized. The server therefore starts and negotiates MCP normally, but live network calls fail closed until TRUTH_SOCIAL_MCP_AUTHORIZED=1 is configured. Set that variable only after obtaining written authorization or an official API agreement.

This project does not bypass Cloudflare, impersonate a browser, or treat a logged-in browser session as API authorization.

Requirements

• Python 3.10+
• An OS credential store supported by Python keyring (macOS Keychain on macOS)
• An externally issued bearer token for authenticated tools
• Written permission or an official Truth Social API agreement for live use
• uv 0.11.26 for the reproducible locked installation below

Install

From a source checkout, install the exact dependency graph recorded in uv.lock:

cd /absolute/path/to/truth-social-mcp
uv sync --locked --extra dev --no-editable --python python3

Portable pip fallback (compatible, but not locked to the exact transitive versions in uv.lock):

cd /absolute/path/to/truth-social-mcp
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/pip install '.[dev]'

The install creates two cwd-independent commands:

• .venv/bin/truthsocial-mcp — MCP stdio server
• .venv/bin/truthsocial-auth — out-of-band token management

The two console commands are part of the installed Python distribution. By contrast, run.sh is a convenience launcher that belongs to the source checkout; it resolves that checkout's .venv regardless of the MCP host's working directory. A wheel installation does not install run.sh or the config-examples directory.

Configure a token safely

Never paste a password, OTP, bearer token, cookie, or access code into an MCP conversation. Import an externally authorized token directly in Terminal:

.venv/bin/truthsocial-auth set-token --username your_handle --scope read
.venv/bin/truthsocial-auth status

Declared scopes are enforced locally as an additional safety gate. If an authorized token is permitted to perform every supported mutation, import it with --scope read --scope write --scope follow; write covers post/media/ like/retruth/delete operations, while follow covers follow/unfollow. Enabling the write environment flag alone never overrides a missing local scope.

The command prompts for the token without echoing it. The token is stored in the operating-system credential store selected by keyring (Keychain on macOS). ~/.truth_social_mcp/session.json contains only non-secret metadata and is written atomically with mode 0600 inside a 0700 directory.

To remove the token:

.venv/bin/truthsocial-auth clear

Run and register

For a normal environment installation, point the MCP host directly at the installed console command:

{
  "mcpServers": {
    "truth-social": {
      "command": "/absolute/path/to/truth-social-mcp/.venv/bin/truthsocial-mcp",
      "args": []
    }
  }
}

Codex registration for the installed console command:

codex mcp add truth-social -- /absolute/path/to/truth-social-mcp/.venv/bin/truthsocial-mcp

When Codex should follow the source checkout's .venv, the repository launcher is equivalent:

codex mcp add truth-social -- /absolute/path/to/truth-social-mcp/run.sh

config-examples/continue_config.yaml is the current Continue configuration. continue_config.legacy.json is retained only for older Continue releases that still use the deprecated JSON configuration.

The server is intentionally useful even when network access is disabled: truth_auth_status reports local configuration without reading the network.

Authorization and environment

After written authorization or an official API agreement, enable live calls in the MCP host's environment:

TRUTH_SOCIAL_MCP_AUTHORIZED=1

Optional settings:

Variable	Default	Purpose
TRUTH_SOCIAL_MCP_AUTHORIZED	0	Permit live API calls after external authorization
TRUTH_SOCIAL_MCP_ALLOW_WRITES	0	Register mutation tools at startup
TRUTH_SOCIAL_MCP_UPLOAD_ROOTS	~/.truth_social_mcp/uploads	:-separated media roots
TRUTH_SOCIAL_MCP_MAX_UPLOAD_MB	25	Maximum local media size
TRUTH_SOCIAL_MCP_TIMEOUT_MS	30000	Request timeout
TRUTH_SOCIAL_MCP_BASE_URL	https://truthsocial.com	API origin; mainly for authorized/test deployments
TRUTH_SOCIAL_MCP_ALLOW_CUSTOM_ORIGIN	0	Permit a non-Truth-Social HTTPS test/authorized origin
TRUTH_SOCIAL_MCP_USER_AGENT	truthsocial-mcp/<version> ...	Honest client identification

Tool surface

Default server tools:

• Local: truth_auth_status, truth_logout
• Public API: truth_instance_info, truth_lookup_user, truth_get_user_posts, truth_get_status
• Token-required reads: truth_verify, truth_get_user, truth_followers, truth_following, truth_home_timeline, truth_trending, truth_get_thread, truth_search, truth_notifications

Truth Social's removed public timeline endpoint is not advertised. Search and trending are correctly marked token-required rather than returning fake empty results.

When both TRUTH_SOCIAL_MCP_AUTHORIZED=1 and TRUTH_SOCIAL_MCP_ALLOW_WRITES=1 are present at server startup, these additional tools are registered:

• truth_post_status, truth_delete_status
• truth_like, truth_unlike
• truth_reblog, truth_unreblog
• truth_follow, truth_unfollow
• truth_upload_media

Every mutation requires schema-level confirm: true. Posting also uses an idempotency key. Uploads accept only relative paths beneath configured roots, reject symlinks and non-regular files, enforce size limits, and verify supported media signatures.

Error behavior

• MCP 2.x validates tool arguments before executing handlers.
• Tool failures return real isError: true results.
• Upstream HTML, response bodies, tokens, cookies, usernames, query strings and local paths are not copied into error messages.
• Stable error codes distinguish missing auth, forbidden access, missing resources/endpoints, rate limits, invalid payloads and network failures.
• Public and authenticated HTTP traffic use physically separate clients; anonymous calls cannot inherit an account token or cookie.

Test

.venv/bin/pytest
.venv/bin/python -m pip check
uv lock --check

The default suite uses in-memory MCP sessions and httpx.MockTransport; it does not contact Truth Social and never performs a real post, like, follow, upload or delete. A subprocess test starts run.sh from outside the repository to protect against cwd/import regressions and also exercises the installed console entrypoint. CI repeats the locked install and full suite on Python 3.10, 3.11, and 3.12.

Known external limitations

Truth Social does not currently publish a stable, generally authorized API contract for this use. Endpoint availability, authentication requirements, Cloudflare policy and account permissions may change independently of this server. Passing local tests proves the MCP implementation, not external API permission or future availability.

License

MIT. See LICENSE.