Content
# twitter_api_safe_relay_mcp
A simple MCP server that forwards HTTP requests to
[`twitter_api_safe_relay`](https://github.com/fa0311/twitter_api_safe_relay).
GitHub: [`nakasyou/twitter_api_safe_relay_mcp`](https://github.com/nakasyou/twitter_api_safe_relay_mcp)
## Getting started
Start the relay server and set its URL in the environment:
```bash
TWITTER_RELAY_BASE_URL=http://localhost:6900 npx twitter_api_safe_relay_mcp
```
Example MCP client configuration:
```json
{
"mcpServers": {
"twitter-api-safe-relay": {
"command": "npx",
"args": ["twitter_api_safe_relay_mcp"],
"env": {
"TWITTER_RELAY_BASE_URL": "http://localhost:6900"
}
}
}
}
```
## Tools
The server exposes two tools:
- `twitter_request_catalog`: Searches the latest request catalog by operation name or path and returns executable templates.
- `twitter_api_request`: Sends a request to the relay using a template.
Start by finding an operation in the catalog. The server fetches
[`requests.ndjson`](https://github.com/fa0311/twitter_api_safe_relay_skills/blob/main/skills/twitter-api-relay/requests.ndjson)
on every catalog call, so updated query IDs and feature flags are picked up automatically.
```json
{
"query": "SearchTimeline",
"limit": 5
}
```
Pass the returned `request` to `twitter_api_request`, changing only the values needed for your task, such as the search query, username, ID, or result count. Do not change `features`, `fieldToggles`, `queryId`, or operation-specific variable names.
Example `twitter_api_request` call:
```json
{
"endpoint": "/i/api/graphql/QUERY_ID/UserByScreenName",
"method": "GET",
"params": {
"variables": {
"screen_name": "example"
},
"features": {}
}
}
```
- `endpoint`: The path sent to the relay. Absolute URLs are not accepted.
- `method`: `GET` (default), `POST`, `PUT`, `PATCH`, or `DELETE`.
- `params`: URL query parameters. Object values are converted to JSON strings.
- `body`: JSON request body.
- `headers`: Optional HTTP headers.
The destination host is always restricted to `TWITTER_RELAY_BASE_URL`.
The `/i/api` prefix is added automatically to GraphQL catalog paths. It is not added to REST paths under `/1.1` or `/2`. Confirm write operations before running them, then verify the result with a read operation. Note that GraphQL responses may contain `errors` even when the HTTP status is 200.
To use a different catalog source, set `TWITTER_REQUESTS_CATALOG_URL`.
## Development and publishing
```bash
npm install
npm run typecheck
npm test
npm run build
npm publish
```
Once published, the server can be run on Node.js 18 or later with `npx twitter_api_safe_relay_mcp`. Bun users can run it with `bunx twitter_api_safe_relay_mcp`.
### Releasing with GitHub Actions
Open the `Release` workflow in GitHub Actions, select the default branch, and choose `patch`, `minor`, or `major`. The workflow calculates the next version from the latest version on npm, runs the tests and build, publishes the package to npm, and creates a GitHub Release.
Before using the workflow, publish the package to npm once and configure a Trusted Publisher for it. The current workflow calculates the next version from the latest version available on npm, so it cannot perform the initial publication of a new package.
- Provider: GitHub Actions
- Organization or user: `nakasyou`
- Repository: `twitter_api_safe_relay_mcp`
- Workflow filename: `release.yml`
- Allowed action: `npm publish`
No long-lived npm token is required. The workflow uses a GitHub-hosted runner, Node.js 24, and npm OIDC Trusted Publishing.
