Tidewave Phoenix — Claude Code MCP server: features and setup
This MCP server connects an agent to a running Phoenix app so it can evaluate Elixir code, inspect logs, and query the development database. It helps when debugging against the app’s live state.
Open on GitHubWhat Tidewave Phoenix does
Tidewave gives an agent access to a Phoenix app running in development. Its tools evaluate Elixir code with access to the app’s runtime and in-memory data, read server logs, and locate module or function definitions in your app and its dependencies. Documentation is matched to package versions recorded in mix.lock.
The server can also run SQL against the development database. Queries target that database, so keep the development environment in mind. To connect, add the tidewave package to mix.exs, plug Tidewave into the app’s endpoint, and configure your MCP client to use /tidewave/mcp at the host and port where the web app runs. An automated installation path uses igniter.
The project recommends Phoenix LiveView v1.1 or later; some debugging options belong in config/dev.exs if they are not already enabled. Worktrees can run web servers on different ports. For that setup, the instructions describe mix tidewave.proxy as an STDIO MCP server that dispatches requests using a port parameter.
What it helps with
- check a function’s behavior in the running app
- inspect request logs to investigate a failure
- run SQL against the development database
- locate a function definition in the app or a dependency
- check documentation against versions in
mix.lock
Example prompts for the agent
- Check what this function returns in the running Phoenix app.
- Read the logs after this request and find the cause of the error.
- Run a SQL query against the development database and verify the result.
How to install Tidewave Phoenix
Install
The MCP registry has no launch command for it: see the repository README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Tidewave Phoenix
How do I install Tidewave Phoenix in Claude Code?
Add tidewave to mix.exs and plug Tidewave into your application endpoint. Then run mix archive.install hex igniter_new, followed by mix igniter.install tidewave. Configure the MCP client to use /tidewave/mcp and the port of your running web app.
What does Tidewave Phoenix do?
It connects an agent to a Phoenix app running in development. The agent can evaluate Elixir code, inspect logs and documentation, locate source definitions, and query the development database.
Which Phoenix LiveView version does Tidewave Phoenix recommend?
The project recommends Phoenix LiveView v1.1 or later. It also calls for debug_heex_annotations and debug_attributes in config/dev.exs when they are not enabled already; Phoenix v1.8+ enables them by default.
