I built a CLI that tells you which MCP servers your repo actually needs

Every week someone posts another "top 10 MCP servers for Claude Code" list. I kept installing things from those lists, forgetting what I had, and once I noticed a project of mine was still running @modelcontextprotocol/server-postgres. That server was archived in May 2025, and Datadog showed its read-only mode can be bypassed with COMMIT; .... Nobody is going to fix it.

So I wrote stackhint. It looks at a repository, checks what is already configured in Claude Code and Codex, and suggests the MCP servers, plugins, skills and CLIs that fit. It explains why each one fits, and it can add a server to your config after showing you the exact change.

It runs locally, has no dependencies and sends nothing anywhere.

What it looks like

$ npx -y github:Protemir/stackhint recommend --task "orders query is slow"
Detected: PostgreSQL, C#, .NET, Redis, GitHub Actions, Docker, EF Core, Jira, OpenAPI, GitHub

1. Recommendation: Postgres MCP Pro  fit 67/100, confidence high
Why now: Service image postgres:17 (docker-compose.yml); your task mentions "query"; 9 database migrations.
Permissions: stackhint uses --access-mode=restricted (read-only transactions).
Actions:
  - stackhint install postgres-mcp-pro --host claude - shows the exact change and asks before writing
  - stackhint try postgres-mcp-pro --host claude - one session without installing
  - stackhint dismiss postgres-mcp-pro --for 14d - remind me later

2. Recommendation: Microsoft Learn MCP Server  fit 58/100, confidence high
Why now: Solution file (DotnetShop.sln); ASP.NET Core web SDK.

3. Recommendation: Atlassian Rovo MCP Server  fit 52/100, confidence high
Why now: Links to acme-demo.atlassian.net Jira (README.md).

Every line in "Why now" points at a file. If your README only says "we might try Kubernetes one day", you get no Kubernetes suggestion. It needs a manifest, a compose image, a dependency or a link.

How it decides

The analyzer reads the files that usually give a stack away: *.csproj, package.json, pyproject.toml, go.mod, compose files, Kubernetes and Terraform files, CI configs, .http files, the key names in .env.example, and links in the README. It also reads git remotes and recent commit subjects. Issue keys like SHOP-123 hint at Jira, and twelve "add migration" commits hint that a project skill would help. It never opens .env, private keys or secret settings files.

Then it reads your setup: ~/.claude.json, .mcp.json, enabled Claude Code plugins and the servers they bundle, ~/.codex/config.toml, Codex plugins, skills. If you already have GitHub's MCP server, or gh on your PATH, it won't push another GitHub integration on you.

The ranking is a plain formula: relevance from the evidence, times value, minus setup cost and risk. The numbers are my estimates, and the tool says so in its output. stackhint explain <id> prints the whole breakdown.

The registry is the actual work

The hard part wasn't the code. It was checking 68 entries by hand: the endpoint, the package name, the read-only flag, whether the project is still maintained. A few things I didn't expect:

• Atlassian's recommended endpoint is now /v2/mcp, and the old /v1/sse stopped working in June.
• kubernetes-mcp-server removed its --read-only flag on main. The next release will reject it, so stackhint pins 0.0.67, where the flag still works.
• Microsoft deleted its MSSQL MCP sample as unsafe in June. The supported route is Data API builder.
• CircleCI's npm package, Notion's local server, Semgrep's standalone repo and Cloudflare's per-product servers are all deprecated or archived.

stackhint knows the old ones too. If it finds one in your config, stackhint check tells you what to replace it with.

Installing without surprises

stackhint install prints a plan first: where it will write, the diff, what the server can access, which environment variables it needs (by name only) and how to undo it. It asks, saves a backup, writes atomically, parses the file back and restores the original if anything looks wrong. stackhint rollback <id> puts the file back byte for byte.

A few rules:

• Read-only variants are the default whenever the vendor offers one.
• Tokens are never written. Claude Code gets ${GITHUB_PERSONAL_ACCESS_TOKEN}, and Codex gets bearer_token_env_var.
• For Codex it appends one [mcp_servers.x] table and leaves the rest of config.toml alone. codex mcp add rewrites the whole table and drops your comments.
• For Claude Code's user and local scopes it calls claude mcp add, because Claude rewrites ~/.claude.json all the time.

Things I learned the hard way

My unit tests were green, then the first run against the real claude binary failed. claude mcp add takes --env with several values, so --env KUBECONFIG=... kubernetes -- npx ... swallows the server name. The fix is to put --env and --header before --transport. There is now a test that runs the real Claude Code and Codex CLIs in CI against configs stackhint wrote.

On native Windows both clients need cmd /c npx ... for npx-based servers, and the tool now writes it that way.

Before the release I put the code through three rounds of review. The worst find: git log inside a scanned repository reads that repository's own .git/config, and with log.showSignature plus a custom gpg.program it runs whatever program the repo points at. So "just read the commit history" could execute code from a repo you only wanted to look at. stackhint now switches all of that off, and a test with a fake signed commit checks it stays off.

Claude Code and Codex in one repo

The same GitHub repo works as a plugin marketplace for both clients. It ships a skill, so you can ask "which MCP servers would help here?", and two hooks. In the default balanced mode, the session-start hook passes up to two high-confidence suggestions to the agent, at most once a day per project. You can turn it off with stackhint config set mode manual.

/plugin marketplace add Protemir/stackhint
/plugin install stackhint@stackhint

codex plugin marketplace add Protemir/stackhint

There is also a read-only MCP server (stackhint mcp) if you prefer that. On purpose, it has no install tool.

Try it

npx -y github:Protemir/stackhint recommend
npx -y github:Protemir/stackhint check

It's MIT and on GitHub: https://github.com/Protemir/stackhint

The registry is where help matters most. If your stack isn't covered, or a vendor changed an endpoint, open an issue or a PR with the source you checked.