Which integrations are available for this server?

Provides tools for introspection and interaction with running Elixir/BEAM applications, including evaluating code, retrieving logs, inspecting processes, ETS tables, supervision trees, and more.

How do I use BeamScope MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BeamScope MCP show me the latest error logs" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

BeamScope MCP

by JediLuke

Overview Schema Related Servers Score Discussions

Local

BeamScope MCP

A robust MCP (Model Context Protocol) server for Elixir applications. BeamScope gives AI coding agents access to your running BEAM application through a resilient TCP architecture that survives app restarts.

Why BeamScope?

BeamScope was built to solve a fundamental problem with HTTP-based MCP servers like TideWave: when your Elixir app restarts, the connection dies and doesn't reconnect.

This is particularly painful during development when you're:

Running mix compile after making changes
Restarting your app to pick up config changes
Experiencing crashes that trigger supervisor restarts

BeamScope uses a standalone TCP architecture where a TypeScript bridge maintains the connection to your AI agent and automatically reconnects when the Elixir app comes back up.

Traditional HTTP-based MCP (TideWave):
┌─────────────┐      HTTP       ┌──────────────────────┐
│  AI Agent   │ ──────────────► │  Phoenix Endpoint    │  ← Dies when app restarts
└─────────────┘                 │  (Plug-based MCP)    │
                                └──────────────────────┘

BeamScope Architecture:
┌─────────────┐     stdio      ┌───────────────────┐     TCP      ┌─────────────────┐
│  AI Agent   │ ─────────────► │  TypeScript       │ ──────────►  │  Elixir         │
│             │                │  Bridge           │  reconnects  │  GenServer      │
└─────────────┘                │  (stays running)  │  on restart  │  (BeamScope)    │
                               └───────────────────┘              └─────────────────┘

Related MCP server: Carto MCP Server

Design Philosophy

Generic Elixir/BEAM, Not Framework-Specific

BeamScope works with any Elixir application, not just Phoenix. The tools are useful across the entire Elixir ecosystem:

project_eval — Evaluate code in your running application
get_logs — Retrieve application logs with filtering
get_docs — Access local documentation for modules and functions

We intentionally excluded framework-specific tools (Ecto, Ash, Phoenix) to keep BeamScope portable and focused on what every BEAM app has in common.

No Default Ports — Fail Loudly

BeamScope has no default port anywhere in the stack. If the port isn't configured, the app crashes at startup with a clear error message telling you exactly what to add to your config.

This prevents the maddening situation where your Elixir app is listening on one port and the MCP bridge is trying to connect on another. Every port must be explicitly configured in both places.

Installation

BeamScope MCP has two components: an Elixir library (TCP server + tools) and a TypeScript bridge (MCP protocol). Both run locally — clone the repo first, then reference it as a path dependency.

1. Clone the repo

cd ~/your/projects  # or wherever you keep local deps
git clone https://github.com/JediLuke/BeamScope-MCP.git beam_scope_mcp

2. Add to your Elixir project

Reference the cloned repo as a path dependency:

# mix.exs
def deps do
  [
    {:beam_scope_mcp, path: "../beam_scope_mcp", only: :dev}
  ]
end

Adjust the path to wherever you cloned it relative to your project.

mix deps.get

3. Configure the port (required)

# config/config.exs (or config/dev.exs)
config :beam_scope_mcp,
  port: 9995,
  app_name: "MyApp"

Optionally allow env var override:

# config/runtime.exs
if port = System.get_env("BEAM_SCOPE_MCP_PORT") do
  config :beam_scope_mcp, port: String.to_integer(port)
end

4. Build the TypeScript bridge

cd /path/to/beam_scope_mcp
npm install
npm run build

5. Configure your AI coding agent

Add BeamScope to your project's .mcp.json:

{
  "mcpServers": {
    "beam-scope-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/beam_scope_mcp/dist/index.js"],
      "env": { "BEAM_SCOPE_MCP_PORT": "9995" }
    }
  }
}

Important: The BEAM_SCOPE_MCP_PORT env var must match the port in your Elixir config. If it's missing, the TypeScript bridge will exit immediately with an error.

Available Tools (20)

Connection

Tool	Description
`connect_beam_scope_mcp`	Establish TCP connection. Port pre-configured via env var.
`get_beam_scope_mcp_status`	Check current connection status.

Core

Tool	Description
`get_logs`	Application logs with tail/grep/level filtering.
`project_eval`	Evaluate Elixir code in the running app with timeout.
`get_docs`	Local documentation for modules/functions via `Code.fetch_docs/1`.

Compilation

Tool	Description
`recompile`	Recompile the project from within the BEAM. Returns errors/warnings.
`reload_module`	Hot-reload a single module from its source file. Fastest feedback loop.
`recompile_deps`	Force recompile dependencies. Args required (e.g. `["--force"]`).

System & Process Introspection

Tool	Description
`get_system_stats`	Memory, schedulers, process counts, uptime, IO stats.
`list_processes`	Filterable/sortable process listing (by name, memory, queue size).
`get_process_info`	Detailed info: function, memory, links, monitors, stacktrace.
`get_process_state`	Internal state of GenServers via `:sys.get_state/1`.
`get_process_dictionary`	Process dictionary metadata (Logger metadata, flags, etc.).

Application & OTP

Tool	Description
`get_app_config`	Runtime application config (what the BEAM has loaded, not files on disk).
`get_supervision_tree`	Recursive OTP supervision tree walk. App name required.

ETS

Tool	Description
`list_ets_tables`	All ETS tables with size, memory, type, protection, owner.
`inspect_ets_table`	Read ETS table contents with row limits and truncation.

Code Intelligence

Tool	Description
`xref_callers`	Find all callers of a module or function via `mix xref`. Impact analysis before refactoring.

Tracing

Tool	Description
`trace_calls`	Trace function calls on a module. Writes to file in `/tmp/beam_scope_traces/` — read results with your file reading tools. Auto-stops at call/time limit.
`stop_trace`	Emergency stop for any running trace. Safe to call even if no trace is running.

Running Multiple Applications

Each application uses a different port:

# App 1: config/config.exs
config :beam_scope_mcp, port: 9995

# App 2: config/config.exs
config :beam_scope_mcp, port: 9994

Each app's .mcp.json passes the matching port via BEAM_SCOPE_MCP_PORT.

Architecture

beam_scope_mcp/
├── lib/
│   ├── beam_scope_mcp.ex           # Public API
│   └── beam_scope_mcp/
│       ├── application.ex          # OTP Application (fail-loudly port config)
│       ├── server.ex               # TCP GenServer + command dispatch
│       ├── log_capture.ex          # Logger handler + circular buffer
│       └── tools/
│           ├── logs.ex             # get_logs
│           ├── eval.ex             # project_eval
│           ├── docs.ex             # get_docs
│           ├── recompile.ex        # recompile, reload_module, recompile_deps
│           ├── system_stats.ex     # get_system_stats
│           ├── processes.ex        # list_processes, get_process_info/state/dictionary
│           ├── app_config.ex       # get_app_config
│           ├── supervision_tree.ex # get_supervision_tree
│           ├── ets.ex              # list_ets_tables, inspect_ets_table
│           ├── xref.ex             # xref_callers
│           └── trace.ex            # trace_calls, stop_trace (writes to /tmp/beam_scope_traces/)
├── src/
│   ├── index.ts                    # MCP server entry point
│   ├── connection.ts               # TCP connection (requires BEAM_SCOPE_MCP_PORT env var)
│   └── tools.ts                    # Tool definitions and handlers
└── dist/                           # Compiled TypeScript (gitignored)

Tool Selection Eval

Tool descriptions are optimized so LLMs select the correct tool for each task. See EVAL.md for 18 test scenarios and results (17/18 pass on Claude Opus 4.6).

Migrating from TideWave

See MIGRATION_FROM_TIDEWAVE.md for a step-by-step guide.

License

MIT

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/JediLuke/BeamScope-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server