Macrocosmos MCP

Using Macrocosmos MCP with Claude Desktop or Cursor

Macrocosmos MCP (Model Context Protocol) lets you integrate SN13 APIs directly into Claude for Desktop, Cursor, or your custom LLM pipeline. Instantly tap into social data, perform live web searches, and explore Hugging Face models — all from your AI environment.

Features

  • 🔍 Query X (Twitter) and Reddit data on demand

  • 🌐 Perform live web search using SN1 miners ( coming soon)

Prerequisites

Install UV package manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

Server setup instructions

This step is required for both Claude Desktop and Cursor — the server is what enables access to the SN1 and SN13 tools.

1. Clone the Repo and Navigate to your project directory

git clone https://github.com/macrocosm-os/macrocosmos-mcp.git
cd macrocosmos-mcp/src

  1. Create and activate a virtual environment

uv venv
source .venv/bin/activate

  1. Initialize the project directory (src)

uv init

  1. Install required dependencies

uv add "mcp[cli]" httpx macrocosmos

  1. Test your MCP server

While it's not required to run the server continuously, performing a quick test ensures that your setup is correct.​

To test your server, execute the following command:​

uv run macrocosmos_mcp.py

This command starts the server and waits for connections. Once you've confirmed it's running correctly, you can stop it by pressing Ctrl+C.​

After this verification, you don't need to run the server manually. As long as the necessary files are present on your local machine, your MCP client (such as Claude Desktop or Cursor) will handle starting the server as needed.

  1. Get the full path to your uv executable:

which uv

Configure Claude Desktop

Run the following command , this will open your Claude configuration file 

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Update with this:

{
    "mcpServers": {
        "macrocosmos": {
            "command": "FULL_PATH_TO_UV",  // Replace with output from `which uv`
            "args": [
                "--directory",
                "/path/to/macrocosmos-mcp",  // Replace with the path to your local clone of macrocosmos-mcp
                "run",
                "src/macrocosmos_mcp.py"
            ],
            "env": {
                "MC_KEY": "your-sdk-api-key"
            }
        }
    }
}

Replace "FULL_PATH_TO_UV" with the full path you got from which uv.

For instance:

/Users/victorkanu/.local/bin/uv

Open Claude desktop

Look for the hammer icon — this confirms your MCP server is running. You’ll now see SN1 and SN13 tools available inside Claude.

Watch a demo 👇

MCP Demo Video

Configure Cursor

You can either update the config file manually or use the built-in UI.

Option 1: Via UI (Recommended)

  • Go to Cursor Settings

  • Navigate to your Cursor settings and select add new global MCP server

Option 2: Manual JSON 

code ~/Library/Application\ Support/Cursor/cursor_mcp_config.json

Paste the same config block (updated with your paths and API keys).

⚠️ Note: In some cases, manually editing this file doesn't activate the MCP server in Cursor. If this happens, use the UI method above for best results.

Update your mcp.json file

Add the following configuration to your mcp.json. This will let you access the available tools. (Same values as shown in the Claude config above.)

{
    "mcpServers": {
        "macrocosmos": {
            "command": "FULL_PATH_TO_UV",  // Replace with output from `which uv`
            "args": [
                "--directory",
                "/path/to/macrocosmos-mcp",  // Replace with the path to your local clone of macrocosmos-mcp
                "run",
                "src/macrocosmos_mcp.py"
            ],
            "env": {
                "MC_KEY": "your-sdk-api-key"
            }
        }
    }
}

Use Agent Mode

In Cursor, make sure you're using Agent Mode in the chat. Agents have the ability to use any MCP tool — including custom ones and those from SN1/SN13. You can ask it questions like:

You can now ask questions or give prompts. Be sure to specify when you want the agent to use MCP tools.

Tool Usage in Action

When the agent responds, you’ll see it indicate which MCP tool it’s using, along with a coherent and context-aware reply.

Troubleshooting

If you encounter any issues:

  1. Ensure you're in the correct directory

  2. Verify that uv is properly installed

  3. Make sure the virtual environment is activated

  4. Check that all dependencies are properly installed

For more on MCPs please refer to the official documentation

PreviousToolsNextSubnet 1 Apex

Last updated