maquina-app/rails-mcp-server: a Ruby MCP server for inspecting Rails projects

What rails-mcp-server solves, and who it is for

A Rails application carries a lot of information in places an LLM cannot see from a single pasted file: the route table, the schema, model associations, controller-to-view wiring, environment configuration. rails-mcp-server is a Ruby implementation of a Model Context Protocol server that exposes those artefacts as MCP tools and resources, so a client such as Claude Desktop can query them instead of guessing. The intended user is a Rails developer who already works with an MCP-capable client and wants the assistant to reason about the real project rather than a partial copy. The README lists the capabilities plainly: browse project files and structures, view routes with filtering options, inspect model information and relationships using Prism static analysis, read the database schema, analyze controller-view relationships, and analyze environment configurations. It also ships documentation resources for Rails, Turbo, Stimulus and Kamal. The project manages multiple Rails projects at once through a projects.yml registry and a switch_project tool, which matters if you keep several applications on one machine. This is not a code-generation service and it is not a Rails plugin. Nothing here is loaded into your application's Gemfile; the gem runs as its own process next to the client.

How the server reaches into a Rails project

The architecture is a separate process, not a Rails engine. You install a gem, the gem provides executables, and your MCP client spawns one of them. In the default STDIO mode the server communicates over standard input and output, which is the pattern Claude Desktop expects. HTTP mode is the alternative: the README states the server then exposes a JSON-RPC endpoint at http://localhost:<port>/mcp/messages and an SSE endpoint at http://localhost:<port>/mcp/sse, with 6029 as the default port. Project discovery is file-based. Configuration follows the XDG Base Directory Specification: on macOS the directory is $XDG_CONFIG_HOME/rails-mcp or ~/.config/rails-mcp when XDG_CONFIG_HOME is unset, and on Windows it is %APPDATA%\rails-mcp. The server creates those directories and an empty projects.yml on first run. Each key in that YAML file is a project name used with switch_project, and each value is a path to the project directory. Model inspection is described as using Prism static analysis, which means relationships are derived by parsing source rather than by booting the application. That is the central design decision: the server reads and parses, it does not execute. The recent release history reinforces it. Versions 1.6.0 and 1.6.1 both concern execute_ruby, one for sandbox hardening and one for process-execution hardening. Version 2.0.0 removed execute_ruby entirely and describes itself as introspection-only. Whatever the intermediate hardening achieved, the maintainers concluded that running arbitrary Ruby from the server was not worth keeping.

Installing the gem and running a first query

Installation is a single gem command. The README states that after installation four executables are on your PATH: rails-mcp-server, rails-mcp-config, rails-mcp-setup-claude and rails-mcp-server-download-resources.

gem install rails-mcp-server

The recommended next step is the interactive configuration tool rather than hand-editing files. It manages projects, downloads the Rails, Turbo, Stimulus and Kamal guides, imports custom markdown documentation, and can write the Claude Desktop configuration for you. The README notes it uses Gum for an enhanced experience when Gum is installed, and falls back to a basic terminal otherwise.

rails-mcp-config

If you prefer to edit configuration directly, the projects.yml file lives in the config directory described above. Each key becomes a project name you can pass to switch_project, and each value is a path.

store: "~/projects/store"
blog: "~/projects/rails-blog"
ecommerce: "/full/path/to/ecommerce-app"

Once the server is registered with a client, the first useful call is to list projects and switch to one, then ask for the route table with a filter. To start the server by hand and confirm it runs, use the default STDIO mode, or HTTP mode if you want to hit the endpoints with a client that speaks HTTP.

rails-mcp-server
rails-mcp-server --mode http
rails-mcp-server --mode http -p 8080

With HTTP mode running on the default port, the JSON-RPC endpoint is at http://localhost:6029/mcp/messages. The README does not document a health-check endpoint, so the practical confirmation is a successful JSON-RPC exchange.

The HTTP mode trade-off and the --bind-all flag

STDIO mode has no network surface at all, which is why it is the default. HTTP mode is for clients that cannot spawn a process. The README is explicit that the HTTP server binds to localhost by default for security, and that --bind-all changes this to 0.0.0.0 for access from other machines on the local network. When --bind-all is active, the README states that access is allowed from local network IP ranges (192.168.x.x, 10.x.x.x) and that the server accepts connections from .local domain names. It also states that security features remain active to validate origins and IP addresses. Read that combination carefully. The flag does not simply open a port; it opens a port and then filters by source address and origin. That is a reasonable default posture, but it is still a service listening on your LAN, and the README's own security note says to use it only on trusted networks because exposing any service increases the attack surface. The filtering rules are also the thing most likely to surprise you: a client on a subnet outside the listed ranges, or reaching the server through a proxy that rewrites the origin, may be rejected for reasons that are not obvious from the error alone. If you only need Claude Desktop on the same machine, STDIO avoids the entire question.

What version 2.0.0 took away

The removal of execute_ruby is the most consequential fact in the release history, and it defines what this tool is now. An MCP server that can run arbitrary Ruby inside your Rails project is a different product from one that can only read it: the first can run a migration, boot a console, or regenerate something, and it also hands the model a code-execution primitive inside your application directory. The 1.6.0 and 1.6.1 releases tried to make that primitive safe, with sandbox hardening and process-execution hardening respectively, and then 2.0.0 deleted it. If you find a tutorial or a client configuration that expects an execute_ruby tool, it predates 2.0.0 and will not work against the current gem. The consequence is a real limitation, not a footnote: the server cannot tell you what a method returns at runtime, cannot run a spec, and cannot apply a pending migration. Static analysis via Prism gives you associations and structure, but anything that depends on evaluated code, metaprogramming resolved at boot, or database state is outside what this server can report. For exploratory questions about a codebase that is a fair trade. For tasks that need execution, it is the wrong tool, and you should reach for a shell or a Rails console instead of trying to route it through MCP.

How it compares with a general-purpose filesystem MCP server

The obvious alternative is a generic filesystem or shell MCP server, which gives a model read access to any directory and often command execution as well. The difference is not the transport, since both speak MCP, but what the model is handed. A filesystem server gives raw file contents and leaves the model to work out which file is the route table and how a controller maps to a view. rails-mcp-server answers those questions directly: routes come back as routes with filtering, models come back with relationships parsed by Prism, and the schema is a first-class resource. The trade-off runs the other way too. A filesystem server works in any repository, Rails or not, and does not need a projects.yml registry or a per-project switch. rails-mcp-server only understands Rails conventions, so a non-Rails Ruby project, a Sinatra app, or a Rails app whose structure has drifted far from convention will yield less than you expect. There is also a documentation dimension: the gem bundles Rails, Turbo, Stimulus and Kamal guides and lets you import custom markdown, which a generic filesystem server does not do unless you point it at those files yourself.

Maintenance, licence, and what to check before adopting

The repository is not archived, and the last push was on 2026-08-17. The 2.0.0 release landed on 2026-08-04, so the project has seen changes within roughly the last six weeks of its recorded history. The gem is MIT licensed, which in practical terms means you can use it commercially and modify it, with the usual requirement to preserve the licence text; that is a description of the licence, not legal advice, and if the licence matters to your organisation's policy you should read LICENSE.txt in the repository. Upgrade cost is concentrated in the 1.6.x to 2.0.0 step. Any client configuration, prompt or script that references execute_ruby breaks, because the tool no longer exists. The README documents the configuration tool, the legacy setup script, and direct configuration, and it documents the commands for both server modes, but it does not document a rollback path if the configuration tool writes a Claude Desktop configuration you do not want. The README does state that the tool creates a backup before making changes, which is the mitigation to rely on. Before adopting, confirm three things: that your MCP client supports STDIO or HTTP with SSE, that the gem version you install is 2.0.0 or later so your expectations match the introspection-only scope, and that every path in projects.yml resolves on the machine running the server, since a stale path will surface as a project that cannot be switched to.

Editorial conclusion

Adopt rails-mcp-server if you want an LLM client to read a Rails codebase without giving it shell access, and you are comfortable editing projects.yml. Skip it if you need the model to run code or migrations: execute_ruby was removed in 2.0.0, so the server is introspection only. Before wiring it into a client, check that your client speaks MCP over STDIO, confirm the gem version you install is 2.0.0 or later, and verify that every project path in projects.yml resolves on the machine running the server.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. maquina-app/rails-mcp-server on GitHub
4. README
5. Releases