# beam-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes [Beam](https://github.com/whyashthakker/beam-cli)'s local, offline risk-scanning to any MCP-compatible host (Claude Desktop, Claude Code, and others).

Beam observes AI agent activity and heuristically flags risky patterns (secrets, destructive commands, exfiltration, unpinned MCP dependencies, etc.) — it never executes, blocks, or approves anything. This server is a thin, read-only wrapper around the [`beam` CLI](https://github.com/whyashthakker/beam-cli): it doesn't reimplement Beam's detection logic, and it doesn't add any capability the CLI doesn't already have.

## Prerequisites

- [Beam CLI](https://github.com/whyashthakker/beam-cli) installed and on `PATH` (`npm install -g beam`).
- Node.js >= 20.17.

## Install & run

```bash
npm install
npm run build
```

Point your MCP host at the built binary over **stdio** (the only transport this server supports today):

```json
{
  "mcpServers": {
    "beam": {
      "command": "node",
      "args": ["/absolute/path/to/beam-mcp/dist/index.js"]
    }
  }
}
```

Or, once published: `npx beam-mcp`.

## Status

We're still building out the MCP layer for Beam. This first slice is intentionally narrow — local, read-only tools. A hosted version will be available at **mcp.agentbeam.com**.

## Tools

All tools are read-only. None of them start, stop, configure, or send data anywhere beyond your own machine (and your own already-running Beam collector, for the one tool that talks to it).

| Tool | What it does |
|---|---|
| `beam_scan_content` | Offline heuristic scan of inline text (a skill/instruction file or MCP config). No network call, no collector required. |
| `beam_scan_path` | Same scan, over a file already on disk. Never modifies the file. |
| `beam_list_rules` | Lists Beam's active detection rules (built-in, custom, sequence), grouped by category. |
| `beam_list_supported_agents` | Lists which coding agents Beam can hook into and whether each hook payload is verified. |
| `beam_collector_status` | Health check against your local Beam collector (`127.0.0.1` only). Tells you to run `beam start` if it isn't up — doesn't start it for you. |

## Security

Security is a core design constraint of this server, not an afterthought — it runs locally, exposes read-only tools only, and takes a conservative approach to anything touching your machine or the Beam collector. See [SECURITY.md](./SECURITY.md) to report a concern.

## Development

```bash
npm run dev        # run src/index.ts directly with tsx
npm run typecheck
```

## License

AGPL-3.0-only — see [LICENSE](./LICENSE). Same license as [beam-cli](https://github.com/whyashthakker/beam-cli), for the same reason: this stays free and open, including for anyone who modifies it and offers it as a hosted service.

## Related

- [beam-cli](https://github.com/whyashthakker/beam-cli) — the CLI and SDK this server wraps. Open source.