Rails Blocks MCP
The Rails Blocks MCP server lets AI coding agents discover docs, inspect examples, and install components through the Rails Blocks CLI. It runs locally in your editor and keeps free component reads on the public static registry.
Before using MCP to install components, complete the Installation guide once for your app. That setup covers Rails Blocks dependencies, Stimulus loading, and custom CSS.
How it works
- 1. Your AI assistant asks: Cursor, Claude, or another MCP app asks Rails Blocks for help.
- 2. Rails Blocks runs locally: The MCP server runs on your computer with the
rails-blocksCLI. - 3. Free components are public: Free components come from the public Rails Blocks registry.
- 4. Pro components require a token: Pro components use your Rails Blocks access token.
Install
Install both the CLI and MCP package. The MCP server expects the rails-blocks executable to be available on your path.
gem install rails-blocks-cli
npm install -g @rails-blocks/mcpgem install rails-blocks-cli
yarn global add @rails-blocks/mcpConfigure your MCP client
Add the Rails Blocks MCP server to your client configuration. If your CLI executable is not on the default path, set RAILS_BLOCKS_CLI.
{
"mcpServers": {
"rails-blocks": {
"command": "rails-blocks-mcp",
"env": {
"RAILS_BLOCKS_CLI": "rails-blocks",
"RAILS_BLOCKS_API_TOKEN": "rb_your_pro_token"
}
}
}
}Setup guides by client
Choose your AI coding tool and add the Rails Blocks MCP server with the configuration format it expects. Keep RAILS_BLOCKS_API_TOKEN only if you want Pro docs, examples, and installs.
Create .cursor/mcp.json in your Rails app for project-specific access, or add the same server through Cursor Settings > MCP.
{
"mcpServers": {
"rails-blocks": {
"command": "rails-blocks-mcp",
"env": {
"RAILS_BLOCKS_CLI": "rails-blocks",
"RAILS_BLOCKS_API_TOKEN": "rb_your_pro_token"
}
}
}
}
Open Claude Desktop Settings > Developer > Edit Config, add this server under mcpServers, then fully quit and restart Claude Desktop.
{
"mcpServers": {
"rails-blocks": {
"command": "rails-blocks-mcp",
"env": {
"RAILS_BLOCKS_CLI": "rails-blocks",
"RAILS_BLOCKS_API_TOKEN": "rb_your_pro_token"
}
}
}
}
Add this to ~/.codex/config.toml. Restart Codex, then use /mcp or your MCP tools list to confirm Rails Blocks is available.
[mcp_servers.rails-blocks]
command = "rails-blocks-mcp"
args = []
env = { RAILS_BLOCKS_CLI = "rails-blocks", RAILS_BLOCKS_API_TOKEN = "rb_your_pro_token" }
Run this from the project where you want Rails Blocks tools available. Use claude mcp list or /mcp to confirm the server is connected.
claude mcp add-json rails-blocks '{"type":"stdio","command":"rails-blocks-mcp","env":{"RAILS_BLOCKS_CLI":"rails-blocks","RAILS_BLOCKS_API_TOKEN":"rb_your_pro_token"}}'
Create .vscode/mcp.json in your Rails app, then open the MCP tools view in VS Code and start the Rails Blocks server.
{
"mcpServers": {
"rails-blocks": {
"command": "rails-blocks-mcp",
"env": {
"RAILS_BLOCKS_CLI": "rails-blocks",
"RAILS_BLOCKS_API_TOKEN": "rb_your_pro_token"
}
}
}
}
Open Windsurf Settings > Cascade > MCP servers, or edit ~/.codeium/windsurf/mcp_config.json and refresh Cascade MCP tools.
{
"mcpServers": {
"rails-blocks": {
"command": "rails-blocks-mcp",
"env": {
"RAILS_BLOCKS_CLI": "rails-blocks",
"RAILS_BLOCKS_API_TOKEN": "rb_your_pro_token"
}
}
}
}
Open Zed settings and add Rails Blocks under context_servers. Zed uses context_servers instead of mcpServers.
{
"context_servers": {
"rails-blocks": {
"command": "rails-blocks-mcp",
"args": [],
"env": {
"RAILS_BLOCKS_CLI": "rails-blocks",
"RAILS_BLOCKS_API_TOKEN": "rb_your_pro_token"
}
}
}
}
Add this to opencode.json in your project or global OpenCode config. OpenCode local MCP servers use the mcp object.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"rails-blocks": {
"type": "local",
"command": [
"rails-blocks-mcp"
],
"enabled": true,
"environment": {
"RAILS_BLOCKS_CLI": "rails-blocks",
"RAILS_BLOCKS_API_TOKEN": "rb_your_pro_token"
}
}
}
}Available tools
rails_blocks_list_components- List all, free, or Pro components from the registry.
rails_blocks_search_docs- Find relevant components by name or keyword.
rails_blocks_get_docs- Fetch free or Pro docs, depending on token access.
rails_blocks_get_examples- Return usage examples for a component.
rails_blocks_install_component- Install one component and its required Stimulus controllers. Supports custom component and Stimulus paths.
rails_blocks_install_all_components- Install all, free, or Pro components matching a filter. Agents should dry-run first unless you explicitly approve writes.
rails_blocks_update_stimulus_controllers- Diff or update Rails Blocks Stimulus controllers directly.
Authorize Pro access
Pro access is handled with access tokens. Run the CLI login once, approve the code in your browser or email, then your MCP server can use Pro docs and packages without sharing your password or browser session.
Sign in to authorize Pro access
The MCP server works with free public components without a token. Sign in with a Pro account to let MCP access Pro docs, examples, and installs.
rails-blocks login
rails-blocks login --email you@example.com
rails-blocks doctor
Prefer not to store a token in your MCP config? Use rails-blocks login once instead. The CLI stores the approved token locally in ~/.rails_blocks/config.json, and the MCP server reuses it.
Agent guidance
- Use
rails_blocks_install_all_componentswhen someone asks to install every component, every free component, or every Pro component. - Use
rails_blocks_install_componentfor one component; it also installs required Stimulus controllers. - Pass
pathandstimulusPathinstead of moving files after install. - Keep
dryRunenabled until the user approves file writes. - If setup, styling, JavaScript behavior, or dependency issues appear, point the user to the Installation guide before retrying component installs.