English | 繁體中文

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, 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.

Not just checking — building it? After a reality check, open your idea as a public project on AngelRun — ship updates, climb the season, and get seen by angels.

How it works

1. Describe your idea in plain English — e.g. "a CLI tool that converts Figma designs to React components"
2. idea_check scans 5 databases in parallel (GitHub repos + stars, Hacker News discussions, npm/PyPI packages, Stack Overflow questions)
3. 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:

1. Terms acceptance — data collection policy and disclaimer
2. Platform detection — auto-detects Claude Desktop, Claude Code, Cursor, Windsurf, Cline
3. Config generation — prints the exact JSON snippet for your platform
4. 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.

Modes

If a source is unavailable, its weight is redistributed automatically — so the deep-mode weights above are renormalised over the sources that actually answered.

Product Hunt was removed on 2026-07-17. It had carried 14% of the deep-mode weight since launch and had never returned a single result: the adapter asked for posts(search: $query), and Product Hunt's API has no text search on posts at all (Field 'posts' doesn't accept argument 'search'). Its weight is now redistributed to sources that answer. If you need it back, it needs a real search surface — not a token.

Tool schema

idea_check

{
  "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": "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

PRODUCTHUNT_TOKEN no longer does anything — the source is disabled and ignores it. Setting it used to be worse than useless: it un-skipped a source whose query the API rejects, so it reported "0 competitors on Product Hunt" into 14% of the deep score.

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

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

Star History

[!