Twitter Username Changes MCP Server

1# Twitter Username Changes MCP Server
2 
3An MCP server that tracks the historical changes of Twitter usernames—frequent screen name changes in crypto projects can be a red flag for potential scam risks.
4 
5![License](https://img.shields.io/badge/License-MIT-green.svg)
6![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
7![Status](https://img.shields.io/badge/Status-Active-brightgreen.svg)
8 
9## Features
10 
11- **Username Change History**: Query the historical usernames of a Twitter user by their current screen name (e.g., `@OSINT_Ukraine` or `@Mormonger`).
12- **Prompt Support**: Includes a prompt template to guide users in formulating queries.
13- **Lightweight Design**: Built with minimal dependencies (`mcp` and `requests`) for easy setup.
14 
15## Installation
16 
17### Prerequisites
18 
19- Python 3.10+
20- `pip` or `uv` for dependency management
21- [Claude Desktop](https://www.anthropic.com/) (optional, for MCP integration)
22 
23### Setup
24 
251. **Clone the Repository**:
26   ```bash
27   git clone https://github.com/kukapay/twitter-username-changes-mcp.git
28   cd twitter-username-changes-mcp
29   ```
30 
312. **Install Dependencies**:
32   ```bash
33   pip install mcp[cli] requests
34   ```
35 
36## Usage
37 
38### Running the Server
39 
40Start the server in development mode to test locally:
41```bash
42mcp dev main.py
43```
44 
45This launches the MCP Inspector, where you can:
46- List available tools (`query_username_changes`).
47- Test queries (e.g., `screen_name: "OSINT_Ukraine"`).
48- Debug prompts.
49 
50### Integrating with Claude Desktop
51 
521. **Configure MCP Server**:
53   Edit the Claude Desktop configuration file:
54   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
55   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
56 
57   Add the server:
58   ```json
59   {
60     "mcpServers": {
61       "twitter-username-changes": {
62         "command": "python",
63         "args": [
64           "/absolute/path/to/twitter-username-changes-mcp/main.py"
65         ]
66       }
67     }
68   }
69   ```
70   Replace `/absolute/path/to/` with the full path to `main.py`.
71 
722. **Install the Server**:
73   ```bash
74   mcp install main.py --name "TwitterUsernameChanges"
75   ```
76 
773. **Query in Claude Desktop**:
78   - Open Claude Desktop and look for the hammer icon (indicating MCP tools).
79   - Enter a query like:
80     ```
81     Show the username change history for Twitter user @OSINT_Ukraine
82     ```
83   - Expected output:
84     ```
85     Username change history for OSINT_Ukraine:
86 
87     User ID 4725638310:
88     - The_HelpfulHand (2016-01-09 to 2020-09-27)
89     - nftpromo_s (2022-02-10 to 2022-02-23)
90     - OSINT_Ukraine (2022-02-24 to 2022-02-25)
91     ```
92 
93### Example Queries
94 
951. **Query `@Mormonger`**:
96   
97   Tool input: `screen_name: "Mormonger"`
98   
99   Output:
100   ```
101   Username change history for Mormonger:
102 
103   User ID 1408886100:
104   - colenoorda (2016-04-02)
105   - Mormonger (2017-01-19 to 2025-02-25)
106   ```
107 
1082. **Query Invalid Handle**:
109   
110   Tool input: `screen_name: "InvalidUser123"`
111   
112   Output:
113   ```
114   No username change history found for InvalidUser123
115   ```
116 
117## License
118 
119This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
120 
121