Install macrocosmos-mcp from PyPI
Install exact version 0.2.2. The executable name has not been verified, so it is intentionally not guessed.
python -m pip install 'macrocosmos-mcp==0.2.2'MCP server intelligence profile
Macrocosmos MCP Server
Enables real-time queries and large-scale data collection from X (Twitter) and Reddit via the Model Context Protocol, powered by Bittensor's Data Universe
1Distribution channel
7Independently observed tools
0Linked remote endpoints
AvailableVersion intelligence
Install and connect
Installation and connection instructions are shown only when supported by retained package, repository, or endpoint evidence.
Identity
| Canonical slug | macrocosmos-mcp-67eea773 | Deployment | Local Only |
|---|---|---|---|
| Canonical package | pypi:macrocosmos-mcp | Repository | macrocosm-os/macrocosmos-mcp |
| First published | Jan 8, 2026 | Latest release | Aug 20, 2026 |
| Last security verification | Aug 22, 2026 | Classification confidence | 90% |
| Publication | Published | Official distribution | Yes |
Distributions
| Channel | Identifier | Current version | Versions | Source |
|---|---|---|---|---|
| pypi | macrocosmos-mcp | 0.2.2 | 2 | Repository |
Current release
| Package | Version | Published / observed | Inventory | Security scan |
|---|---|---|---|---|
| pypimacrocosmos-mcp | 0.2.2Current | Aug 20, 2026 | 7 toolsSucceeded · 0 resources · 0 prompts | Verified clean |
Enterprise protection
Continuously monitor this MCP for security risk
Independently scan the exact version your agents use, receive alerts when its risk changes, and investigate every finding with retained version evidence.
- Independent exact-version security scans
- Continuous release and vulnerability monitoring
- Risk-change alerts with capability context
- Historical evidence and API exports
Custom pricingContact salesTailored to your organization, integrations, data needs, and support requirements.
Current version evidence
| Provenance | artifact_hash_verified | Signature | — |
|---|---|---|---|
| MCP SDK | — | Artifact SHA-256 | 29b57a12750886ccb928bd37179072954644c38a2d2e164d63f284d0477c4167 |
| Scanner | mcp-proof-engine 0.1.0 | Scan completed | Aug 22, 2026 |
| Security rating | — | Methodology | — |
0Proven
704Clean
0Inconclusive
0Flaky
0Errors
Current protocol inventory
2025-06-18Negotiated protocol
macrocosmosServer-reported name
4Capability groups
Aug 22, 2026Observed
Tools 7
| Tool | Category | Annotations | Risk |
|---|---|---|---|
build_dataset
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"
)
Input schema{
"properties": {
"crawler_id": {
"title": "Crawler Id",
"type": "string"
},
"max_rows": {
"default": 10000,
"title": "Max Rows",
"type": "integer"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Email"
},
"redirect_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "https://app.macrocosmos.ai/",
"title": "Redirect Url"
}
},
"required": [
"crawler_id"
],
"title": "build_datasetArguments",
"type": "object"
}Output schema{
"properties": {
"result": {
"title": "Result",
"type": "string"
}
},
"required": [
"result"
],
"title": "build_datasetOutput",
"type": "object"
} | — | — | |
cancel_dataset
Cancel a dataset build or purge a completed dataset.
Parameters:
- dataset_id (str, REQUIRED): The ID of the dataset to cancel/purge
Returns:
- Success or error message
Example:
cancel_dataset(dataset_id="dataset-71e97cfa-xxxx-xxxx-xxxx-33cd91be9028")
Input schema{
"properties": {
"dataset_id": {
"title": "Dataset Id",
"type": "string"
}
},
"required": [
"dataset_id"
],
"title": "cancel_datasetArguments",
"type": "object"
}Output schema{
"properties": {
"result": {
"title": "Result",
"type": "string"
}
},
"required": [
"result"
],
"title": "cancel_datasetOutput",
"type": "object"
} | — | — | |
cancel_gravity_task
Cancel a running Gravity task and stop data collection.
Parameters:
- gravity_task_id (str, REQUIRED): The ID of the gravity task to cancel
Returns:
- Success or error message
Example:
cancel_gravity_task(gravity_task_id="multicrawler-9f518ae4-xxxx-xxxx-xxxx-8b73d7cd4c49")
Input schema{
"properties": {
"gravity_task_id": {
"title": "Gravity Task Id",
"type": "string"
}
},
"required": [
"gravity_task_id"
],
"title": "cancel_gravity_taskArguments",
"type": "object"
}Output schema{
"properties": {
"result": {
"title": "Result",
"type": "string"
}
},
"required": [
"result"
],
"title": "cancel_gravity_taskOutput",
"type": "object"
} | — | — | |
create_gravity_task
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"
)
Input schema{
"properties": {
"tasks": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Tasks",
"type": "array"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Email"
},
"redirect_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "https://app.macrocosmos.ai/",
"title": "Redirect Url"
}
},
"required": [
"tasks"
],
"title": "create_gravity_taskArguments",
"type": "object"
}Output schema{
"properties": {
"result": {
"title": "Result",
"type": "string"
}
},
"required": [
"result"
],
"title": "create_gravity_taskOutput",
"type": "object"
} | — | — | |
get_dataset_status
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")
Input schema{
"properties": {
"dataset_id": {
"title": "Dataset Id",
"type": "string"
}
},
"required": [
"dataset_id"
],
"title": "get_dataset_statusArguments",
"type": "object"
}Output schema{
"properties": {
"result": {
"title": "Result",
"type": "string"
}
},
"required": [
"result"
],
"title": "get_dataset_statusOutput",
"type": "object"
} | — | — | |
get_gravity_task_status
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")
Input schema{
"properties": {
"gravity_task_id": {
"title": "Gravity Task Id",
"type": "string"
},
"include_crawlers": {
"default": true,
"title": "Include Crawlers",
"type": "boolean"
}
},
"required": [
"gravity_task_id"
],
"title": "get_gravity_task_statusArguments",
"type": "object"
}Output schema{
"properties": {
"result": {
"title": "Result",
"type": "string"
}
},
"required": [
"result"
],
"title": "get_gravity_task_statusOutput",
"type": "object"
} | — | — | |
query_on_demand_data
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
Input schema{
"properties": {
"source": {
"title": "Source",
"type": "string"
},
"usernames": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Usernames"
},
"keywords": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Keywords"
},
"start_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Start Date"
},
"end_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "End Date"
},
"limit": {
"default": 10,
"title": "Limit",
"type": "integer"
},
"keyword_mode": {
"default": "any",
"title": "Keyword Mode",
"type": "string"
}
},
"required": [
"source"
],
"title": "query_on_demand_dataArguments",
"type": "object"
}Output schema{
"properties": {
"result": {
"title": "Result",
"type": "string"
}
},
"required": [
"result"
],
"title": "query_on_demand_dataOutput",
"type": "object"
} | — | — |
Resources 0
- None observed.
Resource templates 0
- None observed.
Prompts 0
- None observed.
Remote endpoints
| Endpoint | Transport | Authentication | Health | Observed |
|---|---|---|---|---|
| No verified remote endpoint is linked. | ||||
Macrocosmos MCP Server questions
How do I install Macrocosmos MCP Server?
Install the selected package version with: python -m pip install 'macrocosmos-mcp==0.2.2'
What tools does Macrocosmos MCP Server provide?
Macrocosmos MCP Server exposed 7 tools during independent protocol observation, including build_dataset, cancel_dataset, cancel_gravity_task, create_gravity_task, get_dataset_status, get_gravity_task_status, query_on_demand_data.
Is Macrocosmos MCP Server secure?
Our scanner tested version 0.2.2 without proving a finding in the methods exercised. This is not a guarantee that every deployment is secure.
Explore related MCP server guides
Curated product and capability guides containing this catalog record.