Macrocosmos MCP Server

Fetch real-time social media data from X (Twitter) and Reddit through the Macrocosmos SN13 network. IMPORTANT: This tool requires 'source' parameter to be either 'X' or 'REDDIT' (case-sensitive). Parameters: - source (str, REQUIRED): Data platform - must be 'X' or 'REDDIT' - usernames (List[str], optional): Up to 5 usernames to monitor. * For X: '@' symbol is optional (e.g., ['elonmusk', '@spacex'] both work) * NOT available for Reddit - keywords (List[str], optional): Up to 5 keywords/hashtags to search * For X: any keywords or hashtags (e.g., ['AI', 'crypto', '#bitcoin']) * For Reddit: subreddit names (e.g., ['r/astronomy', 'space']) or 'r/all' for all subreddits - start_date (str, optional): Start date/datetime in YYYY-MM-DD or ISO format * Examples: '2024-04-01' or '2024-01-01T00:00:00Z' * Defaults to 24 hours ago from current time if not specified - end_date (str, optional): End date/datetime in YYYY-MM-DD or ISO format * Examples: '2024-04-25' or '2024-06-03T23:59:59Z' * Defaults to current time if not specified - limit (int, optional): Maximum number of results to return (range: 1-1000, default: 10) - keyword_mode (str, optional): How to match keywords - 'any' (default) or 'all' * 'any': returns posts matching ANY of the keywords * 'all': returns posts matching ALL of the keywords Default Behavior (when dates not specified): The tool searches the last 24 hours (from current time back to 24 hours ago). Usage Examples: 1. Get recent tweets from specific users: query_on_demand_data(source='X', usernames=['@elonmusk', '@spacex'], limit=20) 2. Search tweets by keywords in last 24 hours: query_on_demand_data(source='X', keywords=['AI', 'machine learning'], limit=30) 3. Monitor specific users AND filter by keywords: query_on_demand_data(source='X', usernames=['@nasa'], keywords=['space', 'mars'], limit=20) 4. Monitor Reddit subreddits: query_on_demand_data(source='REDDIT', keywords=['r/astronomy', 'space'], limit=50) 5. Search across all of Reddit with date range: query_on_demand_data(source='REDDIT', keywords=['r/all', 'space'], start_date='2025-04-01', end_date='2025-04-02', limit=50) 6. Strict keyword matching (requires ALL keywords): query_on_demand_data(source='X', keywords=['AI', 'machine learning'], keyword_mode='all', limit=30) 7. Precise datetime range search: query_on_demand_data(source='X', keywords=['Bitcoin'], start_date='2024-06-01T00:00:00Z', end_date='2024-06-03T23:59:59Z', limit=100) Returns: JSON object containing: - status: "success" or error information - data: Array of posts/tweets with full content, user information, engagement metrics, timestamps, platform-specific metadata, and media attachments - meta: Processing statistics (miners queried, response rates, items returned, etc.) Platform-Specific Notes: - X (Twitter): '@' symbol is optional for usernames - Reddit: Does NOT support username filtering, only subreddit/keyword searches - All timestamps returned in UTC format

Create a Gravity task for large-scale data collection from X (Twitter) or Reddit. Use this for collecting large datasets over time (up to 7 days). For quick queries (up to 1000 results), use query_on_demand_data instead. The task registers on the network within 20 minutes and collects data for 7 days. You'll receive an email notification when the dataset is ready for download. Parameters: - tasks (List[dict], REQUIRED): List of task objects, each containing: * platform (str): 'x' or 'reddit' * topic (str): The hashtag/subreddit to monitor - For X: MUST start with '#' or '$' (e.g., '#ai', '$BTC') - plain keywords are rejected! - For Reddit: subreddit name (e.g., 'r/MachineLearning') * keyword (str, optional): Additional keyword filter within the topic - Filters posts to only those containing this keyword - Example: topic='#Bittensor', keyword='dTAO' -> only #Bittensor posts mentioning 'dTAO' - name (str, optional): Name for the task (helps organize multiple tasks) - email (str, optional): Email address for notification when dataset is ready - redirect_url (str, optional): URL to redirect to from the email notification Returns: - gravity_task_id: Unique identifier to track and manage the task Examples: 1. Basic collection: create_gravity_task( tasks=[{"platform": "x", "topic": "#ai"}], name="AI Tweets" ) 2. With keyword filter: create_gravity_task( tasks=[{"platform": "x", "topic": "#Bittensor", "keyword": "dTAO"}], name="Bittensor dTAO mentions" ) 3. Multiple platforms: create_gravity_task( tasks=[ {"platform": "x", "topic": "#ai", "keyword": "LLM"}, {"platform": "reddit", "topic": "r/MachineLearning"} ], name="AI Data Collection", email="user@example.com" )

Get the status of a Gravity task and see how much data has been collected. Parameters: - gravity_task_id (str, REQUIRED): The ID of the gravity task to check - include_crawlers (bool, default: True): Whether to include detailed crawler information Set to True to see records_collected and bytes_collected for each crawler Returns: - Task status (Running, Completed, Pending, etc.) - Task name and start time - List of crawler IDs (needed for build_dataset) - When include_crawlers=True: records_collected, bytes_collected per crawler Example: get_gravity_task_status(gravity_task_id="multicrawler-9f518ae4-xxxx-xxxx-xxxx-8b73d7cd4c49")

Build a dataset from collected data before the 7-day task completion. Use this when you have enough data and don't want to wait for the full collection period. WARNING: Building a dataset will STOP the crawler and de-register it from the network. The crawler will no longer collect new data after this operation. Parameters: - crawler_id (str, REQUIRED): The ID of the crawler to build dataset from (Get this from get_gravity_task_status response - look for 'crawler_ids' field) - max_rows (int, default: 10000): Maximum number of rows to include in the dataset - email (str, optional): Email address for notification when dataset is ready - redirect_url (str, optional): URL to redirect to from the email notification Returns: - dataset_id: Unique identifier to track the dataset build - Build status and progress information (10 steps total) Example: build_dataset( crawler_id="crawler-0-multicrawler-9f518ae4-xxxx", max_rows=10000, email="user@example.com" )

Get the status of a dataset build and download links when ready. Parameters: - dataset_id (str, REQUIRED): The ID of the dataset to check Returns: - Build status (Running, Completed, etc.) - Progress steps (10 total steps) - When completed: Download URLs for Parquet files - File metadata (size, row count, expiration date) Example: get_dataset_status(dataset_id="dataset-71e97cfa-xxxx-xxxx-xxxx-33cd91be9028")