# 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](https://help.truthsocial.com/legal/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`:

```bash
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`):

```bash
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:

```bash
.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:

```bash
.venv/bin/truthsocial-auth clear
```

## Run and register

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

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

Codex registration for the installed console command:

```bash
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:

```bash
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:

```bash
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

```bash
.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](LICENSE).