modernity-mcp

MCP (Model Context Protocol) server for Modernity — connect live data to Cursor and Claude, and build apps with the Modernity API.

Prerequisites

• Node.js 18 or newer
• API key from modernity.live (get one free, no credit card)

Quick Start

# Verify your key works
npx -y modernity-mcp --key=YOUR_API_KEY --test

If you see Success! API is online and your key is valid., you're ready to connect.

Connect to Cursor

1. Open Cursor Settings (Cmd+Shift+J or Ctrl+Shift+J)
2. Go to Features → MCP
3. Click + Add New MCP Server
4. Fill in:
   • Name: Modernity
   • Type: stdio
   • Command: npx
   • Args: -y modernity-mcp --key=YOUR_API_KEY
5. Set MODERNITY_API_KEY in env, or pass --key=YOUR_API_KEY in Args
6. Save. The dot turns green when connected.

Connect to Claude Desktop

1. Open your Claude config file:
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add to the mcpServers block:

{
  "mcpServers": {
    "modernity": {
      "command": "npx",
      "args": ["-y", "modernity-mcp"],
      "env": {
        "MODERNITY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

3. Restart Claude Desktop. Look for the plug icon.

Authentication

Provide your API key in one of two ways:

• Environment variable: MODERNITY_API_KEY=your_key
• CLI argument: --key=your_key

The server exits immediately with an error if no key is provided.

Tool Reference

Live Data Tools

Use these to answer questions, get real-time information, and explore what's happening now.

| Tool | Description | |------|-------------| | get_recent_data | Fetch recent messages from the live stream. Optional: limit, source, category | | query_topic | Semantic search across all sources. Required: topic. Optional: timeframe, limit, format | | multi_schema_query | Query across data types (doc, ticker, news, geo_alert). Required: query. Optional: schemas, timeframe, limit | | analyze_topic | AI-powered topic analysis with recommendations. Required: topic | | get_sources | List all 23+ available data sources and categories | | get_stream_stats | Get live stream health and statistics | | get_key_info | Check API key tier, usage, and rate limits | | check_health | Verify the API is online | | get_pricing | Get all pricing tiers and features |

Developer / Builder Tools

Use these to build applications with the Modernity API — generate code, get docs, and start new projects.

| Tool | Description | |------|-------------| | get_api_docs | Complete API endpoint documentation with request/response schemas. Optional: endpoint (recent, query, multi, live, sources, snapshot, counts, analyze, keys, auth, all) | | generate_integration | Generate ready-to-use code with auth, error handling, and retry logic. Optional: language (python, javascript, typescript, curl), endpoint (recent, query, multi, live_sse, full_client, etc.), use_case | | get_quickstart | Step-by-step framework integration guide. Optional: framework (python, flask, fastapi, django, nextjs, express, react, cloudflare-workers, etc.), use_case |

Resources

| URI | Description | |-----|-------------| | modernity://health | API health status | | modernity://sources | Available data sources | | modernity://pricing | Pricing tiers | | modernity://docs/getting-started | Getting started guide | | modernity://docs/endpoints | API endpoint reference | | modernity://docs/authentication | Authentication & rate limits | | modernity://docs/errors | Error codes & troubleshooting | | modernity://docs/examples | Code examples (Python, JS, curl) |

Example Prompts

Information Questions (uses live data tools)

• "What's happening on Hacker News right now?"
• "Search for Bitcoin developments in the last hour"
• "Show me recent earthquake alerts"
• "What's the latest from arXiv on machine learning?"
• "Check the stream status"

Building with Modernity (uses developer tools)

• "How do I integrate Modernity into my Next.js app?"
• "Generate Python code to monitor crypto prices using Modernity"
• "Show me the API docs for the /v1/query endpoint"
• "Help me build a Flask app that searches Modernity for news"
• "Generate a full Python client for the Modernity API"
• "What error codes does the Modernity API return?"

Troubleshooting

| Issue | Fix | |-------|-----| | "MODERNITY_API_KEY... is required" | Add the key via env or --key= | | "Your API key is invalid" | Regenerate at modernity.live/dashboard | | "Rate limit exceeded" | Wait before retrying; check tier limits with get_key_info | | "Tool not found" | Restart Cursor/Claude after config changes | | Connection fails | Run npx -y modernity-mcp --key=YOUR_KEY --test to isolate the issue |

Publish to npm

cd mcp
npm login
npm publish --access public