scrapebadger-mcp 0.1.0__tar.gz

scrapebadger_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run linter
+        run: uv run ruff check src/ tests/
+
+      - name: Run formatter check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Run type checker
+        run: uv run mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v
+        env:
+          SCRAPEBADGER_API_KEY: "test_key_for_ci"
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

scrapebadger_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Configure trusted publishing at:
+        # https://pypi.org/manage/account/publishing/
+        # Owner: scrape-badger
+        # Repository: scrapebadger-mcp
+        # Workflow: publish.yml
+        # Environment: pypi

scrapebadger_mcp-0.1.0/.gitignore

@@ -0,0 +1,86 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local development
+*.local
+.envrc

scrapebadger_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ScrapeBadger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scrapebadger_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,448 @@
+Metadata-Version: 2.4
+Name: scrapebadger-mcp
+Version: 0.1.0
+Summary: MCP server for ScrapeBadger - Twitter/X scraping API for AI agents
+Project-URL: Homepage, https://scrapebadger.com
+Project-URL: Documentation, https://docs.scrapebadger.com
+Project-URL: Repository, https://github.com/scrape-badger/scrapebadger-mcp
+Project-URL: Issues, https://github.com/scrape-badger/scrapebadger-mcp/issues
+Author-email: ScrapeBadger <support@scrapebadger.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,api,chatgpt,claude,cursor,llm,mcp,model-context-protocol,scraping,twitter,x
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: scrapebadger>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://scrapebadger.com/logo-dark.png" alt="ScrapeBadger" width="400">
+</p>
+
+<h1 align="center">ScrapeBadger MCP Server</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/scrapebadger-mcp/"><img src="https://img.shields.io/pypi/v/scrapebadger-mcp.svg" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/scrapebadger-mcp/"><img src="https://img.shields.io/pypi/pyversions/scrapebadger-mcp.svg" alt="Python versions"></a>
+  <a href="https://github.com/scrape-badger/scrapebadger-mcp/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/scrapebadger-mcp.svg" alt="License"></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-blue" alt="MCP Compatible"></a>
+</p>
+
+<p align="center">
+  <strong>Give your AI agents access to Twitter/X data via the Model Context Protocol</strong>
+</p>
+
+---
+
+## What is this?
+
+ScrapeBadger MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that enables AI assistants like **Claude**, **ChatGPT**, **Cursor**, **Windsurf**, and other MCP-compatible clients to access Twitter/X data through the [ScrapeBadger API](https://scrapebadger.com).
+
+**With this MCP server, your AI can:**
+
+- Get Twitter user profiles, followers, and following lists
+- Search and retrieve tweets
+- Access trending topics globally or by location
+- Explore Twitter lists and communities
+- Search for places and geolocated content
+
+## Quick Start
+
+### 1. Get Your API Key
+
+Sign up at [scrapebadger.com](https://scrapebadger.com) and get your API key.
+
+### 2. Install
+
+```bash
+# Using uvx (recommended - no installation needed)
+uvx scrapebadger-mcp
+
+# Or install globally with pip
+pip install scrapebadger-mcp
+
+# Or with uv
+uv tool install scrapebadger-mcp
+```
+
+### 3. Configure Your AI Client
+
+#### Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "scrapebadger": {
+      "command": "uvx",
+      "args": ["scrapebadger-mcp"],
+      "env": {
+        "SCRAPEBADGER_API_KEY": "sb_live_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to your Cursor MCP settings (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "scrapebadger": {
+      "command": "uvx",
+      "args": ["scrapebadger-mcp"],
+      "env": {
+        "SCRAPEBADGER_API_KEY": "sb_live_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Windsurf
+
+Add to your Windsurf MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "scrapebadger": {
+      "command": "uvx",
+      "args": ["scrapebadger-mcp"],
+      "env": {
+        "SCRAPEBADGER_API_KEY": "sb_live_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+#### VS Code with Copilot
+
+Add to your VS Code settings (`.vscode/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "scrapebadger": {
+      "command": "uvx",
+      "args": ["scrapebadger-mcp"],
+      "env": {
+        "SCRAPEBADGER_API_KEY": "sb_live_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 4. Start Using It!
+
+Once configured, simply ask your AI to fetch Twitter data:
+
+> "Get the profile of @elonmusk"
+
+> "Search for tweets about AI agents"
+
+> "What's trending on Twitter right now?"
+
+> "Find the top 10 Python developers on Twitter"
+
+---
+
+## Available Tools
+
+The MCP server provides 17 tools organized into categories:
+
+### User Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_twitter_user_profile` | Get a user's profile by username (bio, followers, following, etc.) |
+| `get_twitter_user_about` | Get extended "About" info (account location, username history) |
+| `search_twitter_users` | Search for users by query |
+| `get_twitter_followers` | Get a user's followers |
+| `get_twitter_following` | Get accounts a user follows |
+
+### Tweet Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_twitter_tweet` | Get a single tweet by ID |
+| `get_twitter_user_tweets` | Get recent tweets from a user |
+| `search_twitter_tweets` | Search for tweets (supports Twitter search operators) |
+
+### Trend Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_twitter_trends` | Get global trending topics (optionally by category) |
+| `get_twitter_place_trends` | Get trends for a specific location (by WOEID) |
+
+### Geo Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_twitter_places` | Search for Twitter places by name |
+
+### List Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_twitter_list_detail` | Get details about a Twitter list |
+| `search_twitter_lists` | Search for Twitter lists |
+| `get_twitter_list_tweets` | Get tweets from a list |
+
+### Community Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_twitter_community_detail` | Get details about a Twitter community |
+| `search_twitter_communities` | Search for communities |
+
+---
+
+## Example Conversations
+
+### Research a Twitter Account
+
+**You:** Get the profile and recent tweets from @sama
+
+**Claude:** I'll fetch Sam Altman's Twitter profile and recent tweets.
+
+*Uses `get_twitter_user_profile` and `get_twitter_user_tweets`*
+
+```
+Sam Altman (@sama)
+- 3.2M followers, 1,847 following
+- Bio: "ceo of openai"
+- Joined: December 2008
+
+Recent tweets:
+1. "excited to share..." (245K likes)
+2. "the future of ai..." (180K likes)
+...
+```
+
+### Monitor Trending Topics
+
+**You:** What's trending in tech on Twitter today?
+
+**Claude:** I'll check the current trending topics.
+
+*Uses `get_twitter_trends` with category="news"*
+
+```
+Top Tech Trends:
+1. #GPT5 - 125,000 tweets
+2. Apple Vision Pro - 89,000 tweets
+3. #AGI - 45,000 tweets
+...
+```
+
+### Competitive Analysis
+
+**You:** Compare the Twitter engagement of Stripe, Square, and PayPal
+
+**Claude:** I'll gather data on all three companies' Twitter profiles.
+
+*Uses `get_twitter_user_profile` for each company*
+
+```
+| Company | Followers | Following | Engagement Rate |
+|---------|-----------|-----------|-----------------|
+| Stripe  | 892K      | 1,245     | 2.3%           |
+| Square  | 1.2M      | 567       | 1.8%           |
+| PayPal  | 2.1M      | 234       | 0.9%           |
+```
+
+---
+
+## Configuration Options
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SCRAPEBADGER_API_KEY` | Yes | Your ScrapeBadger API key |
+
+### Using with Docker
+
+```dockerfile
+FROM python:3.12-slim
+
+RUN pip install scrapebadger-mcp
+
+ENV SCRAPEBADGER_API_KEY=your_key_here
+
+CMD ["scrapebadger-mcp"]
+```
+
+### Using with Python Directly
+
+```bash
+# Set your API key
+export SCRAPEBADGER_API_KEY="sb_live_your_key_here"
+
+# Run the server
+python -m scrapebadger_mcp.server
+```
+
+---
+
+## Error Handling
+
+The MCP server handles common errors gracefully:
+
+| Error | Description | Solution |
+|-------|-------------|----------|
+| `AuthenticationError` | Invalid API key | Check your `SCRAPEBADGER_API_KEY` |
+| `RateLimitError` | Too many requests | Wait and retry, or upgrade your plan |
+| `InsufficientCreditsError` | Out of credits | Purchase more at scrapebadger.com |
+| `NotFoundError` | User/tweet not found | Verify the username or tweet ID |
+
+---
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/scrape-badger/scrapebadger-mcp.git
+cd scrapebadger-mcp
+
+# Install dependencies
+uv sync --dev
+
+# Set your API key
+export SCRAPEBADGER_API_KEY="sb_live_your_key_here"
+```
+
+### Running Locally
+
+```bash
+# Run the MCP server directly
+uv run python -m scrapebadger_mcp.server
+
+# Or use the CLI
+uv run scrapebadger-mcp
+```
+
+### Testing
+
+```bash
+# Run tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=src/scrapebadger_mcp
+```
+
+### Code Quality
+
+```bash
+# Lint
+uv run ruff check src/
+
+# Format
+uv run ruff format src/
+
+# Type check
+uv run mypy src/
+```
+
+---
+
+## Troubleshooting
+
+### "SCRAPEBADGER_API_KEY environment variable is required"
+
+Make sure you've set the API key in your MCP configuration:
+
+```json
+{
+  "env": {
+    "SCRAPEBADGER_API_KEY": "sb_live_your_key_here"
+  }
+}
+```
+
+### Server not showing in Claude Desktop
+
+1. Restart Claude Desktop after changing the config
+2. Check the config file path is correct for your OS
+3. Verify JSON syntax is valid (no trailing commas)
+
+### "uvx: command not found"
+
+Install `uv` first:
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### Rate limit errors
+
+ScrapeBadger has usage limits based on your plan. If you're hitting limits:
+
+1. Reduce request frequency
+2. Use pagination with smaller `max_results`
+3. Upgrade your plan at [scrapebadger.com](https://scrapebadger.com)
+
+---
+
+## Related Projects
+
+- [ScrapeBadger Python SDK](https://github.com/scrape-badger/scrapebadger-python) - Official Python SDK
+- [ScrapeBadger Node.js SDK](https://github.com/scrape-badger/scrapebadger-node) - Official Node.js SDK
+- [ScrapeBadger API Docs](https://docs.scrapebadger.com) - Full API documentation
+
+---
+
+## Support
+
+- **Documentation:** [docs.scrapebadger.com](https://docs.scrapebadger.com)
+- **Issues:** [GitHub Issues](https://github.com/scrape-badger/scrapebadger-mcp/issues)
+- **Email:** support@scrapebadger.com
+- **Discord:** [Join our community](https://discord.gg/scrapebadger)
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  Made with love by <a href="https://scrapebadger.com">ScrapeBadger</a>
+</p>