idea-reality-mcp

How to check if someone already built your app idea — automatically.

idea-reality-mcp is an MCP server that scans GitHub, npm, PyPI, Hacker News, Product Hunt, and Stack Overflow to check if your startup idea already exists. It returns a 0–100 reality score with evidence, trend detection, and pivot suggestions — so your AI agent can decide whether to build, pivot, or kill the idea before writing any code.

When to use this: You're about to start a new project and want to know if similar tools already exist, how competitive the space is, and whether the market is growing or declining.

How it works

Describe your idea in plain English — e.g. "a CLI tool that converts Figma designs to React components"
idea_check scans 6 databases in parallel (GitHub repos + stars, Hacker News discussions, npm/PyPI packages, Product Hunt launches, Stack Overflow questions)
Get a 0–100 reality score with trend direction (accelerating/stable/declining), top competitors, and AI-generated pivot suggestions

What you get

You: "AI code review tool"

idea_check →
├── reality_signal: 92/100
├── trend: accelerating ↗
├── market_momentum: 73/100
├── GitHub repos: 847 (45% created in last 6 months)
├── Top competitor: reviewdog (9,094 ⭐)
├── npm packages: 56
├── HN discussions: 254 (trending up)
└── Verdict: HIGH — market is accelerating, find a niche fast

One score. Six sources. Trend detection. Your agent decides what to do next.

Quick Start

# 1. Install
uvx idea-reality-mcp

# 2. Add to your agent
claude mcp add idea-reality -- uvx idea-reality-mcp   # Claude Code

3. Ask your agent: "Before I start building, check if this already exists: a CLI tool that converts Figma designs to React components"

That's it. The agent calls idea_check and returns: reality_signal, top competitors, and pivot suggestions.

Claude Desktop / Cursor — add to config JSON:

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

Config location: macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json · Cursor .cursor/mcp.json

Smithery (remote, no local install):

npx -y @smithery/cli install idea-reality-mcp --client claude

Setup & Configuration

First-time guided setup:

idea-reality setup

This walks you through:

Terms acceptance — data collection policy and disclaimer
Platform detection — auto-detects Claude Desktop, Claude Code, Cursor, Windsurf, Cline
Config generation — prints the exact JSON snippet for your platform
Health check — verifies MCP server, tools, and scoring engine

Platform Configs

idea-reality config              # interactive menu
idea-reality config claude_code  # auto-installs via CLI
idea-reality config cursor       # prints Cursor config
idea-reality config raw_json     # generic MCP JSON

Supported: Claude Desktop · Claude Code · Cursor · Windsurf · Cline · Smithery · Docker

Health Check

idea-reality doctor        # core checks (~2s)
idea-reality doctor --full # + GitHub API, all 6 sources, Anthropic API

Usage

MCP tool call (any MCP-compatible agent):

{
  "tool": "idea_check",
  "arguments": {
    "idea_text": "a CLI tool that converts Figma designs to React components",
    "depth": "deep"
  }
}

REST API (no MCP required):

curl -X POST https://idea-reality-mcp.onrender.com/api/check \
  -H "Content-Type: application/json" \
  -d '{"idea_text": "AI code review tool", "depth": "quick"}'

Python:

import httpx

resp = httpx.post("https://idea-reality-mcp.onrender.com/api/check", json={
    "idea_text": "AI code review tool",
    "depth": "deep"
})
print(resp.json()["reality_signal"])  # 0-100

Free. No API key required.

Why not just Google it?

Your AI agent never Googles anything before it starts building. idea_check runs inside your agent — it triggers automatically whether you remember or not.

| | Google | ChatGPT | idea-reality-mcp | |---|---|---|---| | Who runs it | You, manually | You, manually | Your agent, automatically | | Output | 10 blue links | "Sounds promising!" | Score 0-100 + evidence | | Sources | Web pages | None (LLM) | GitHub + HN + npm + PyPI + PH + SO | | Price | Free | Paywall | Free & open-source (MIT) |

Modes

| Mode | Sources | Use case | |------|---------|----------| | quick (default) | GitHub + HN | Fast sanity check, < 3 seconds | | deep | GitHub + HN + npm + PyPI + Product Hunt + Stack Overflow | Full competitive scan |

| Source | Quick | Deep | |--------|-------|------| | GitHub repos | 60% | 22% | | GitHub stars | 20% | 9% | | Hacker News | 20% | 14% | | npm | — | 18% | | PyPI | — | 13% | | Product Hunt | — | 14% | | Stack Overflow | — | 10% |

If a source is unavailable, its weight is redistributed automatically.

Tool schema

`idea_check`

| Parameter | Type | Required | Description | |-------------|---------------------------|----------|--------------------------------------| | idea_text | string | yes | Natural-language description of idea | | depth | "quick" | "deep" | no | "quick" = GitHub + HN (default). "deep" = all 6 sources |

{
  "reality_signal": 72,
  "duplicate_likelihood": "high",
  "trend": "accelerating",
  "sub_scores": { "market_momentum": 73 },
  "evidence": [
    {"source": "github", "type": "repo_count", "query": "...", "count": 342},
    {"source": "github", "type": "max_stars", "query": "...", "count": 15000},
    {"source": "hackernews", "type": "mention_count", "query": "...", "count": 18},
    {"source": "npm", "type": "package_count", "query": "...", "count": 56},
    {"source": "pypi", "type": "package_count", "query": "...", "count": 23},
    {"source": "producthunt", "type": "product_count", "query": "...", "count": 8},
    {"source": "stackoverflow", "type": "question_count", "query": "...", "count": 120}
  ],
  "top_similars": [
    {"name": "user/repo", "url": "https://github.com/...", "stars": 15000, "description": "..."}
  ],
  "pivot_hints": [
    "High competition. Consider a niche differentiator...",
    "The leading project may have gaps in..."
  ]
}

CI: Auto-check on Pull Requests

Use idea-check-action to validate feature proposals:

name: Idea Reality Check
on:
  issues:
    types: [opened]

jobs:
  check:
    if: contains(github.event.issue.labels.*.name, 'proposal')
    runs-on: ubuntu-latest
    steps:
      - uses: mnemox-ai/idea-check-action@v1
        with:
          idea: ${{ github.event.issue.title }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

Optional config

export GITHUB_TOKEN=ghp_...        # Higher GitHub API rate limits
export PRODUCTHUNT_TOKEN=your_...  # Enable Product Hunt (deep mode)

Auto-trigger: Add one line to your CLAUDE.md, .cursorrules, or .github/copilot-instructions.md:

When starting a new project, use the idea_check MCP tool to check if similar projects already exist.

Roadmap

[x] v0.1 — GitHub + HN search, basic scoring
[x] v0.2 — Deep mode (npm, PyPI, Product Hunt), keyword extraction
[x] v0.3 — 3-stage keyword pipeline, Chinese term mappings, LLM-powered search
[x] v0.4 — Score History, Agent Templates, GitHub Action
[x] v0.5 — Temporal signals, trend detection, market momentum
[x] v0.6 — Onboarding CLI (idea-reality setup, config, doctor)
[ ] v1.0 — Idea Memory Dataset (opt-in anonymous logging)

Star History

Found a blind spot?

If the tool missed obvious competitors or returned irrelevant results:

Open an issue with your idea text and the output
We'll improve the keyword extraction for your domain

Contributing

See CONTRIBUTING.md (繁體中文).

License

MIT — see LICENSE

Built by Mnemox AI · [email protected]

idea reality

Installation

Transport

Tools (9)

Dokumentation