io.github.Sorsa-io/sorsa-mcp

Sorsa MCP

An MCP server for the Sorsa.io API v3 — access to X/Twitter data: profiles, tweets, search, follow/retweet checks, Sorsa scores, lists and communities.

The server exposes 40 tools, one per API endpoint.

Installation

npm install
npm run build

Or, once published, run it with no install via npx (see below).

Configuration

You need a Sorsa API key. It is read from the SORSA_API_KEY environment variable and sent with every request in the ApiKey header.

Connecting a client

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project).

Using the published npm package (nothing to install, npx fetches it):

{
  "mcpServers": {
    "sorsa": {
      "command": "npx",
      "args": ["-y", "sorsa-mcp"],
      "env": {
        "SORSA_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Or running from a locally built checkout:

{
  "mcpServers": {
    "sorsa": {
      "command": "node",
      "args": ["D:\\Code\\Cursor Projects\\Sorsa_MCP\\dist\\index.js"],
      "env": {
        "SORSA_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json and add the same mcpServers block as above, then restart the app.

Local check

# build
npm run build

# run (communicates over stdio — easiest to test through a client)
SORSA_API_KEY=YOUR_KEY npm start

The quickest way to confirm your key works is the get_key_usage_info tool — it returns your remaining request balance and the key's expiration date.

Available tools

Profiles: get_user_info, get_user_info_batch, get_followers, get_following, get_verified_followers, get_account_about

Tweets: get_tweet_info, get_tweet_info_bulk, get_user_tweets, get_tweet_comments, get_tweet_quotes, get_retweeters, get_article, get_trends

Search: search_tweets, search_users, search_mentions, get_space_info

Communities: get_community_members, get_community_tweets, search_community_tweets

Checks: check_follow, check_comment, check_quoted, check_retweet, check_community_member

Sorsa metrics: get_sorsa_score, get_sorsa_score_changes, get_followers_stats, get_top_followers, get_top_following, get_new_followers_7d, get_new_following_7d

Lists: get_list_members, get_list_tweets, get_list_followers

Utilities: username_to_id, id_to_username, link_to_id, get_key_usage_info

Project layout

• src/endpoints.ts — a declarative table of every endpoint (method, path, parameters). To add or change a tool, edit this file only.
• src/index.ts — the HTTP client plus tool registration driven by that table.

How it works

Each endpoint is one entry in ENDPOINTS. Based on each field's in (path / query / body), the handler routes arguments into the URL path, the query string, or the JSON body, then sends the request to Sorsa with the ApiKey header. The response is returned to the client as JSON text.

License

MIT