Skip to content
Back to search

tidewave_phoenix

MCP server with runtime-level tools for Phoenix development

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tidewave-ai/tidewave_phoenix with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tidewave-ai/tidewave_phoenix'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tidewave-ai--tidewave-phoenix/badge.svg)](/listings/tidewave-ai--tidewave-phoenix)

HTML

<a href="/listings/tidewave-ai--tidewave-phoenix"><img src="/api/listings/tidewave-ai--tidewave-phoenix/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Add the Tidewave hex package to your app

Option 1: Manually

Add the `tidewave` package to your `mix.exs`:

def deps do
  [
    {:tidewave, "~> 0.9", only: :dev},
    {:phoenix, ...},
  ]
end

Then, for Phoenix applications, go to your `lib/my_app_web/endpoint.ex` and right above the `if code_reloading? do` block, add:

+  if Mix.env() == :dev do
+    plug Tidewave
+  end

   if code_reloading? 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 :phoenix_live_view, > debug_heex_annotations: true, > debug_attributes: 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:

# install igniter_new if you haven't already
mix archive.install hex igniter_new

# 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/your_app_web`).

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](https://tidewave.hexdocs.pm/mcp_claude_code.html) - [Codex](https://tidewave.hexdocs.pm/mcp_codex.html) - [Cursor](https://tidewave.hexdocs.pm/mcp_cursor.html) - [Neovim](https://tidewave.hexdocs.pm/mcp_neovim.html) - [OpenCode](https://tidewave.hexdocs.pm/mcp_opencode.html) - [VS Code](https://tidewave.hexdocs.pm/mcp_vscode.html) - [Others](https://tidewave.hexdocs.pm/mcp.html)

> [!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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 195 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Tidewave Phoenix
  2. Tidewave Phoenix is an MCP server that provides runtime-level tools for developing Phoenix apps using coding agents.
  3. Your agent will be able to use this MCP server to talk to your running Phoenix app in development to:
  4. - execute code in the context of the running app (like an IEx session for agents)
  5. - read the app's live logs
  6. - query your development database
  7. - get source locations of modules and functions
  8. - read documentation pinned to the exact hex package versions your project depends on
  9. This MCP server is an open-source component of [Tidewave](https://tidewave.ai), the agentic development environment for Phoenix and Rails.
  10. You can use this project as a standalone MCP server or integrated with the [Tidewave product](https://tidewave.ai) by following the installation instructions below.
  11. ## Installation
  12. ### 1. Add the Tidewave hex package to your app
  13. #### Option 1: Manually
  14. Add the `tidewave` package to your `mix.exs`:
  15. ```elixir
  16. def deps do
  17. [
  18. {:tidewave, "~> 0.9", only: :dev},
  19. {:phoenix, ...},
  20. ]
  21. end
  22. ```
  23. Then, for Phoenix applications, go to your `lib/my_app_web/endpoint.ex` and right above the `if code_reloading? do` block, add:
  24. ```diff
  25. + if Mix.env() == :dev do
  26. + plug Tidewave
  27. + end
  28. if code_reloading? do
  29. ```
  30. > [!TIP]
  31. > Tidewave works best with Phoenix LiveView v1.1 or later. Once you update it,
  32. > make sure to enable the following options in your `config/dev.exs`:
  33. >
  34. > ```elixir
  35. > config :phoenix_live_view,
  36. > debug_heex_annotations: true,
  37. > debug_attributes: true
  38. > ```
  39. >
  40. > Those are enabled by default for Phoenix v1.8+ apps.
  41. #### Option 2: Using Igniter
  42. Alternatively, you can use `igniter` to automatically install Tidewave MCP into an existing Phoenix application:
  43. ```sh
  44. # install igniter_new if you haven't already
  45. mix archive.install hex igniter_new
  46. # install tidewave
  47. mix igniter.install tidewave
  48. ```
  49. #### Umbrella projects
  50. For umbrella projects, you can follow the manual steps above in the application that defines your Phoenix endpoint (typically `apps/your_app_web`).
  51. ### 2. Add the Tidewave MCP to your agent/editor
  52. 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`.
  53. We also have specific instructions for:
  54. - [Claude Code](https://tidewave.hexdocs.pm/mcp_claude_code.html)
  55. - [Codex](https://tidewave.hexdocs.pm/mcp_codex.html)
  56. - [Cursor](https://tidewave.hexdocs.pm/mcp_cursor.html)
  57. - [Neovim](https://tidewave.hexdocs.pm/mcp_neovim.html)
  58. - [OpenCode](https://tidewave.hexdocs.pm/mcp_opencode.html)
  59. - [VS Code](https://tidewave.hexdocs.pm/mcp_vscode.html)
  60. - [Others](https://tidewave.hexdocs.pm/mcp.html)
  61. > [!TIP]
  62. > If you are using worktrees, you are likely running your web server
  63. > on different ports, and therefore there isn't a single host and port
  64. > combo you can use.
  65. >
  66. > In such cases, you may want to add `mix tidewave.proxy` as STDIO MCP
  67. > instead, which adds a "port" parameter to all tool definitions, and
  68. > is responsible to dispatch to the correct application.
  69. ## Usage
  70. 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.
  71. ## Available MCP tools
  72. ### `project_eval`
  73. 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.
  74. [![project_eval demo](readme/project_eval-poster.png)](https://asciinema.org/a/1260494)
  75. 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.
  76. ### `execute_sql_query`
  77. Executes a SQL query within your app's development database.
  78. [![execute_sql_query demo](readme/execute_sql_query-poster.png)](https://asciinema.org/a/1260504)
  79. Your agent can use it to run any SQL against your development database. Useful for the agent to verify the result of an action.
  80. ### `get_docs`
  81. Get the documentation for a given module/function. It consults the exact versions locked in your project's mix.lock, ensuring you get correct information.
  82. [![get_docs demo](readme/get_docs-poster.png)](https://asciinema.org/a/1260511)
  83. ### `get_logs`
  84. Reads logs written by the server.
  85. [![get_logs demo](readme/get_logs-poster.png)](https://asciinema.org/a/1260515)
  86. Your agent can use it to see what happened after a request. For example, reading the request log and backtrace when something misbehaves.
  87. ### `get_source_location`
  88. Get the source location for a given module/function, across both your app and its dependencies.
  89. [![get_source_location demo](readme/get_source_location-poster.png)](https://asciinema.org/a/1260518)
  90. Your agent can use it to jump straight to where a module/function is defined, by file and line, instead of grepping for it, including when the definition lives in a hex dependency.
  91. ## Troubleshooting
  92. ### Using multiple hosts/subdomains
  93. If you are using multiple hosts/subdomains during development, you must use `*.localhost`, as such domains are considered secure by browsers. Additionally, add the following immediately `@session_options` definition in your `lib/your_app_web/endpoint.ex`:
  94. ```elixir
  95. @session_options [
  96. # ... your configuration
  97. ]
  98. if code_reloading? do
  99. @session_options Keyword.merge(@session_options, same_site: "None", secure: true)
  100. end
  101. ```
  102. The above will allow your application to run embedded within Tidewave across multiple subdomains, as long as it is using a secure context (such as `admin.localhost`, `www.foobar.localhost`, etc).
  103. ### Content security policy
  104. If you have enabled Content-Security-Policy, Tidewave will automatically enable "unsafe-eval" under `script-src` in order for contextual browser testing to work correctly. It also disables the `frame-ancestors` directive. This is done only in the environments that Tidewave is loadead (development by default).
  105. ## Configuration
  106. You may configure the `Tidewave` plug using the following syntax:
  107. ```elixir
  108. plug Tidewave, options
  109. ```
  110. The following options are available:
  111. * `:allow_remote_access` - Tidewave only allows requests from localhost by default, even if your server listens on other interfaces, for security purposes. Read [our security guidelines for more information and when to allow remote access](https://tidewave.hexdocs.pm/security.html). Use this option with extreme care and, once enabled, ensure you have an authentication proxy in front of your app.
  112. * `:allowed_origins` - a list of values matched against the `Origin` and `Host` headers to prevent cross origin and DNS rebinding attacks. Each value must be a string of shape `[scheme:]//host[:port]`, where both scheme and port are optional. The host may also start with "*". Only the host is compared against the `Host` header. IP addresses, `localhost`, and `*.localhost` are always allowed as hosts. When not set, defaults to the host of your Phoenix endpoint URL. Example: `["//localhost:8000", "//*.test"]`
  113. * `:inspect_opts` - custom options passed to `Kernel.inspect/2` when formatting some tool results. Defaults to: `[charlists: :as_lists, limit: 50, pretty: true]`
  114. * `:team` - set your Tidewave Team configuration, such as `team: [id: "my-company"]`
  115. * `:toolbar` - controls whether the Tidewave toolbar is injected into your HTML pages. Defaults to `true`
  116. * `tmp_dir` - temporary directory Tidewave uses for screenshots and recordings. It must be a relative directory to the current application root. Defaults to `tmp`, storing files under `tmp/tidewave/screenshots` and `tmp/tidewave/recordings`
  117. ## License
  118. Copyright (c) 2025 Dashbit
  119. Licensed under the Apache License, Version 2.0 (the "License");
  120. you may not use this file except in compliance with the License.
  121. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
  122. Unless required by applicable law or agreed to in writing, software
  123. distributed under the License is distributed on an "AS IS" BASIS,
  124. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  125. See the License for the specific language governing permissions and
  126. limitations under the License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.