# 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.