portfolio-mcp

An MCP server that reads a directory full of projects and tells you what is in there: what each one is built with, whether it is in git, where it is deployed, what has gone stale, and which ones are closest to earning money.

It is read-only. It never writes to, moves, or deletes anything it scans.

Install

npx portfolio-mcp --root /path/to/your/projects

Register it with Claude Code:

claude mcp add --scope user portfolio \
  -e PORTFOLIO_ROOT=/path/to/your/projects \
  -- npx -y portfolio-mcp

Or in any client that reads mcpServers:

{
  "mcpServers": {
    "portfolio": {
      "command": "npx",
      "args": ["-y", "portfolio-mcp"],
      "env": { "PORTFOLIO_ROOT": "/path/to/your/projects" }
    }
  }
}

Related MCP server: codescan-mcp

Configuration

Nothing is hardcoded. The scan root is resolved in this order:

1. --root <path> (or --root=<path>) on the command line

2. the PORTFOLIO_ROOT environment variable

3. the process working directory

_archive, _backups, node_modules, .git, and dotted directories are skipped.

Tools

Inventory

Deployment

Revenue

Maintenance

What it touches

Being clear about this, because the server reads a directory you care about:

• Reads only. No tool writes, moves, renames, or deletes a file.

• Path containment. A project name is one directory entry. Separators, .., absolute paths, drive letters, null bytes, and Windows device names are rejected, and the resolved path is then checked to be inside the configured root. There is no way to make it read a sibling directory.

• No shell. Every subprocess runs through execFileSync with an argument array. Directory names are never concatenated into a command string.

• Subprocesses. git for repository state, and npm / pip only inside outdated_deps.

• Network. outdated_deps alone reaches the npm and PyPI registries, because that is what npm outdated, npm audit, and pip list --outdated do. Set PORTFOLIO_OFFLINE=1 and it refuses instead. Every other tool is local.

• No credentials. The server reads no tokens and sends nothing anywhere.

Scoring

revenue_scan and find_opportunities produce a 1 to 10 score from signals that are cheap to detect: deployment configuration, an auth library, a payment library, a landing page entry point, a README, a git remote, an API framework, then a category multiplier. It is a triage heuristic for sorting a large directory, not a valuation. Treat the ranking as "look at these first", not as a number that means anything on its own.

Development

npm ci
npm run build
npm test          # builds, then runs node --test
npm pack --dry-run

License

MIT. See LICENSE.