tidewave-ai/tidewave_phoenix

Tidewave Phoenix is an MCP server that provides runtime-level tools for developing Phoenix apps using coding agents.
Your agent will be able to use this MCP server to talk to your running Phoenix app in development to:
execute code in the context of the running app (like an IEx session for agents)
read the app's live logs
query your development database
get source locations of modules and functions
read documentation pinned to the exact hex package versions your project depends on
This MCP server is an open-source component of Tidewave, the agentic development environment for Phoenix and Rails.
You can use this project as a standalone MCP server or integrated with the Tidewave product by following the installation instructions below.
## Installation
### 1. Add the Tidewave hex package to your app
#### Option 1: Manually
Add the tidewave package to your mix.exs:
elixir
def deps do
{:tidewave, "~> 0.9", only: :dev},
{:phoenix, ...},
end
Then, for Phoenix applications, go to your lib/myappweb/endpoint.ex and right above the if codereloading? do block, add:
diff
if Mix.env() == :dev do
plug Tidewave
end
if codereloading? do
> [!TIP]
> Tidewave works best with Phoenix LiveView v1.1 or later. Once you update it,
> make sure to enable the following options in your config/dev.exs:
> elixir
> config :phoenixliveview,
> debugheexannotations: true,
> debugattributes: true
> Those are enabled by default for Phoenix v1.8+ apps.
#### Option 2: Using Igniter
Alternatively, you can use igniter to automatically install Tidewave MCP into an existing Phoenix application:
sh
# install igniternew if you haven't already
mix archive.install hex igniternew
# install tidewave
mix igniter.install tidewave
#### Umbrella projects
For umbrella projects, you can follow the manual steps above in the application that defines your Phoenix endpoint (typically apps/yourappweb).
### 2. Add the Tidewave MCP to your agent/editor
Add the Tidewave MCP server to your editor or MCP client configuration as the type "http" (streamable), pointing to the /tidewave/mcp path and port your web application is running at. For example, http://localhost:4000/tidewave/mcp.
We also have specific instructions for:
Claude Code
Codex
Cursor
Neovim
OpenCode
VS Code
Others
> [!TIP]
> If you are using worktrees, you are likely running your web server
> on different ports, and therefore there isn't a single host and port
> combo you can use.
> In such cases, you may want to add mix tidewave.proxy as STDIO MCP
> instead, which adds a "port" parameter to all tool definitions, and
> is responsible to dispatch to the correct application.
## Usage
As with any other MCP server, your agent will call the tools exposed by the Tidewave MCP whenever it sees fit. But you can also prompt it to call them explicitly.
## Available MCP tools
### projecteval
Evaluates Elixir code within your running application, giving the agent access to your runtime, dependencies, and in-memory data. It's like an IEx for the agent.
Your agent can use it when it would rather run code than assume behavior, grounding its next step in what the running app actually does. For example, calling a function to see what comes back or reproducing a failing code path against live app state to debug it.