idea-reality-mcp

Pre-build reality check for AI coding agents. Stop building what already exists.

v0.3 is coming — LLM-powered keyword extraction for much better accuracy. Get notified when it drops + help shape the roadmap.

What it does

idea-reality-mcp is an MCP server that provides the idea_check tool. When an AI coding agent is about to build something, it can call this tool to check whether similar projects already exist across multiple sources.

Quick mode (default): GitHub + Hacker News Deep mode: GitHub + HN + npm + PyPI + Product Hunt (all sources in parallel)

The tool returns:

• reality_signal (0-100): How much existing work overlaps with your idea
• duplicate_likelihood: low / medium / high
• evidence: Raw search data from all queried sources
• top_similars: Top similar projects from GitHub, npm, PyPI, and Product Hunt
• pivot_hints: 3 actionable suggestions based on the competitive landscape

Quickstart

# Install and run
uvx idea-reality-mcp

# Or clone and run locally
git clone https://github.com/mnemox-ai/idea-reality-mcp.git
cd idea-reality-mcp
uv run idea-reality-mcp

Optional: Environment variables

# Higher GitHub API rate limits
export GITHUB_TOKEN=ghp_your_token_here

# Enable Product Hunt search (deep mode)
export PRODUCTHUNT_TOKEN=your_ph_token_here

Claude Desktop config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "idea-reality": {
      "command": "uvx",
      "args": ["idea-reality-mcp"]
    }
  }
}

Cursor config

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "idea-reality": {
      "command": "uvx",
      "args": ["idea-reality-mcp"]
    }
  }
}

Recommended: Add to your CLAUDE.md

To ensure your AI agent automatically uses idea_check when you discuss new ideas, add this line to your project's CLAUDE.md (or equivalent instructions file):

When users discuss new project ideas or ask about competition, use the idea_check tool from idea-reality-mcp.

This helps the agent recognize when to call the tool without you having to explicitly name it.

Tool schema

idea_check

Input:

Output:

{
  "reality_signal": 72,
  "duplicate_likelihood": "high",
  "evidence": [
    {"source": "github", "type": "repo_count", "query": "...", "count": 342, "detail": "..."},
    {"source": "github", "type": "max_stars", "query": "...", "count": 15000, "detail": "..."},
    {"source": "hackernews", "type": "mention_count", "query": "...", "count": 18, "detail": "..."},
    {"source": "npm", "type": "package_count", "query": "...", "count": 56, "detail": "..."},
    {"source": "pypi", "type": "package_count", "query": "...", "count": 23, "detail": "..."},
    {"source": "producthunt", "type": "product_count", "query": "...", "count": 8, "detail": "..."}
  ],
  "top_similars": [
    {"name": "user/repo", "url": "https://github.com/...", "stars": 15000, "updated": "...", "description": "..."},
    {"name": "npm:cool-pkg", "url": "https://npmjs.com/...", "stars": 0, "updated": "", "description": "..."},
    {"name": "pypi:cool-pkg", "url": "https://pypi.org/...", "stars": 0, "updated": "", "description": "..."}
  ],
  "pivot_hints": [
    "High existing competition detected. Consider a niche differentiator...",
    "The leading project (user/repo, 15000 stars) may have gaps...",
    "Consider building an integration or plugin..."
  ],
  "meta": {
    "checked_at": "2026-02-25T10:30:00+00:00",
    "sources_used": ["github", "hackernews", "npm", "pypi", "producthunt"],
    "depth": "deep",
    "version": "0.2.0"
  }
}

Scoring weights

Quick mode: GitHub repos 60% + GitHub stars 20% + HN mentions 20%

Deep mode: GitHub repos 25% + GitHub stars 10% + HN mentions 15% + npm 20% + PyPI 15% + Product Hunt 15%

If Product Hunt is unavailable (no token), its weight is automatically redistributed to the other sources.

Sample prompts

Before building, check if this already exists: a CLI tool that converts
Figma designs to React components automatically

idea_check("AI-powered code review bot for GitHub PRs", depth="deep")

Check market reality: real-time collaborative markdown editor with AI
autocomplete

Roadmap

• v0.1 — GitHub + HN search, basic scoring
• v0.2 — depth: "deep" with npm, PyPI, Product Hunt; improved keyword extraction (current)
• v0.3 — LLM-powered keyword extraction and semantic similarity
• v0.4 — Trend detection and timing analysis

License

MIT — see LICENSE