idea-reality-mcp: a pre-build reality check your coding agent runs by itself

The problem: agents build before anyone checks whether the thing exists

The README makes a narrow claim about who this is for: you are about to start a new project and want to know whether similar tools already exist, how crowded the space is, and whether interest is rising or falling. The tool is aimed at that moment, not at ongoing competitive research.

The argument the project makes for itself is about timing and agency. Its comparison table puts Google and ChatGPT on the side of tools a human runs manually, and idea-reality-mcp on the side of something the agent triggers. That distinction is the whole product. A developer who remembers to search will find competitors with a browser; an agent that never searches will scaffold a repository for a product that already has five equivalents on npm. Whether that failure mode is common enough to justify a server is the open question, and the answer depends on how much unreviewed code your agent writes.

Five parallel scans and a weighted score: the mechanism

The flow is three steps. You describe the idea in plain English, for example a CLI tool that converts Figma designs to React components. The server then scans five databases in parallel: GitHub repositories and stars, Hacker News discussions, npm and PyPI packages, and Stack Overflow questions. What comes back is a 0-100 reality score, a trend direction (accelerating, stable or declining), top competitors and pivot suggestions.

The score is a weighted sum, and the weights differ by mode. In quick mode GitHub repos carry 60%, GitHub stars 20% and Hacker News 20%. In deep mode the weight spreads across six slots: GitHub repos 22%, stars 9%, Hacker News 14%, npm 18%, PyPI 13%, Stack Overflow 10%. If a source does not answer, its weight is redistributed across the sources that did, so the published deep-mode numbers are renormalised at runtime rather than fixed.

That renormalisation is the most interesting design decision in the repository and also the easiest to misread. A deep result computed without PyPI is not the same measurement as one computed with it, yet both surface as a single 0-100 number. The README documents the redistribution but does not say the response flags which sources were missing, so read the evidence fields, not just the score.

Product Hunt was removed because it never returned a result

The README is unusually direct about a failure. Product Hunt carried 14% of the deep-mode weight since launch and was removed on 2026-07-17 because it had never returned a single result: the adapter called posts(search: $query), and the README states Product Hunt's API has no such query. That is roughly four months of a sixth of the deep score being silently redistributed.

The removal is the right call, and the episode is worth keeping in mind for a different reason. A missing source does not produce an error, it produces a renormalised score. The system degrades quietly by design. Any adapter that starts returning empty results for a different reason, a rate limit or a changed schema, would look identical from the outside. The repository ships a doctor command with a --full flag that adds GitHub API, all six sources and the Anthropic API to the core checks, which is the intended way to catch that class of problem.

Installing idea-reality-mcp and running a first check

The README's quick start is two commands. The first runs the server from PyPI without a permanent install, and the second registers it with Claude Code under the name idea-reality.

uvx idea-reality-mcp
claude mcp add idea-reality -- uvx idea-reality-mcp

Any MCP client can be configured by hand instead. The README gives this JSON for Claude Desktop and Cursor, with the config living at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, or .cursor/mcp.json for Cursor.

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

There is a guided path for first-time setup. Running idea-reality setup walks through terms acceptance, platform detection for Claude Desktop, Claude Code, Cursor, Windsurf and Cline, config generation, and a health check. The config subcommand takes a platform argument, so idea-reality config cursor prints the Cursor snippet and idea-reality config claude_code installs through the CLI. To verify the environment before trusting a score, run idea-reality doctor for the roughly two-second core check, or idea-reality doctor --full to exercise every source.

Once registered, you ask the agent in ordinary language, and the agent calls idea_check with an idea_text argument and a depth of quick or deep. If you would rather not run MCP at all, the same engine is reachable over HTTP with no API key.

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"}'

The README shows the deep-mode response shape as a tree containing reality_signal, trend, market_momentum, repository counts, a top competitor and a verdict. Treat those numbers as a starting point for reading the evidence, not as a decision.

What the score cannot tell you, and the mode that is too slow

The quick mode is documented as under three seconds and covers only GitHub and Hacker News. That is a sanity check, not a competitive scan, and the weights make it lopsided: 60% of the score in quick mode is a repository count. A crowded but dead space and a crowded and growing one can land in the same band if the trend signal is weak.

The deep mode is the honest one and it is also the slow one. Five network calls to third-party APIs, one of which is GitHub, means rate limits and latency you do not control. The README does not document what happens to a deep check when GitHub throttles an unauthenticated caller, and it does not document rollback or caching behaviour. The redistribution rule is the only documented mitigation, and it hides the failure rather than surfacing it.

It is also the wrong tool for anything that is not a software product. The sources are GitHub, npm, PyPI, Hacker News and Stack Overflow. A physical product, a service business or a regulated offering has no meaningful footprint in any of them, so a low score means the sources are empty, not that the market is. The README's own framing, checking whether someone already built your app idea, is the boundary. Stay inside it.

Against a plain web search, and against building your own scanner

The obvious alternative is a person searching GitHub and Hacker News by hand, which is what most teams do today. The difference is not the data, since both see the same public sources. It is who runs the query and what comes back. A manual search returns pages you have to read and interpret; idea_check returns a number, a trend label and a list of named competitors. The manual search is more accurate and slower, and it only happens if someone remembers.

The second alternative is writing the scan yourself against the GitHub and Hacker News APIs. That is a weekend of work for the two quick-mode sources, and the project's own README documents how the third-party integrations can rot, with Product Hunt as the worked example. What you would be adopting is the scoring weights, the redistribution logic and the adapter maintenance, not the API calls. If you disagree with the weights, which put 22% on repository count and 9% on stars in deep mode, you are better off with your own script than with a fork of someone else's scale.

Maintenance mode, MIT licensing and the upgrade path

The README states the project's status as of August 2026: maintenance mode, the tool works, it stays free and open source, the hosted API remains up, bug reports are reviewed, and no new features are planned. The last push to the repository was on 2026-08-11. The most recent release listed is v0.5.0 from 2026-03-11, with v0.4.0 and v0.3.4 in the weeks before it, while pyproject.toml declares version 0.5.1. That gap between the declared version and the newest release tag is worth checking against the changelog before you pin anything.

Upgrade cost is low by construction. The runtime dependencies are fastmcp, httpx and click, Python 3.11 or newer is required, and the package installs from PyPI with uvx, so there is no build step and no service to operate unless you use the hosted endpoint. The Dockerfile is a python:3.11-slim image that copies src/ and runs pip install, with idea-reality-mcp as the entrypoint. Because the project is in maintenance mode, expect the third-party adapters to be the part that breaks first, since those are the pieces that depend on APIs the maintainers do not control.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are kept. The repository also ships TERMS.md and SECURITY.md, and the setup command includes a terms acceptance step covering a data collection policy and disclaimer, which suggests the hosted API has terms separate from the code licence. Read both before pointing a team at the hosted endpoint. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt it if your agent already writes code before anyone checks the market, and you want that check to happen without a human remembering to run it. Skip it if you need sub-second latency, a maintained roadmap, or a score you can defend to an investor: the README itself says no new features are planned, and the score is a weighted count of public artifacts, not a market study. Verify first that the MCP client you actually use is one of the six the setup command detects, then run idea-reality doctor --full and confirm all six sources answer from your network before you trust a deep-mode result.

Frequently asked questions

Official sources

1. License: MIT
2. mnemox-ai/idea-reality-mcp on GitHub
3. Project website
4. README
5. Releases