twitter_api_safe_relay_mcp

A simple MCP server that forwards HTTP requests to twitter_api_safe_relay.

GitHub: nakasyou/twitter_api_safe_relay_mcp

Getting started

Start the relay server and set its URL in the environment:

TWITTER_RELAY_BASE_URL=http://localhost:6900 npx twitter_api_safe_relay_mcp

Example MCP client configuration:

{
  "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 on every catalog call, so updated query IDs and feature flags are picked up automatically.

{
  "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:

{
  "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

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.