Skip to content
Back to search

ruby_llm-mcp

Full-featured MCP support for Ruby and RubyLLM—making it easy to build structured, composable LLM workflows in pure Ruby.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/patvice--ruby-llm-mcp/badge.svg)](/listings/patvice--ruby-llm-mcp)

HTML

<a href="/listings/patvice--ruby-llm-mcp"><img src="/api/listings/patvice--ruby-llm-mcp/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.

Add to your Gemfile:

gem "ruby_llm-mcp"

Then run:

bundle install

If you want the official SDK adapter, also add:

gem "mcp", "~> 0.7"

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 · 218 lines

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

  1. <div align="center">
  2. <img src="docs/assets/images/rubyllm-mcp-logo-text.svg#gh-light-mode-only" alt="RubyLLM::MCP" height="120" width="250">
  3. <img src="docs/assets/images/rubyllm-mcp-logo-text-white.svg#gh-dark-mode-only" alt="RubyLLM::MCP" height="120" width="250">
  4. <strong>MCP for Ruby and RubyLLM, as easy as possible.</strong>
  5. [![Gem Version](https://badge.fury.io/rb/ruby_llm-mcp.svg)](https://badge.fury.io/rb/ruby_llm-mcp)
  6. [![Gem Downloads](https://img.shields.io/gem/dt/ruby_llm-mcp)](https://rubygems.org/gems/ruby_llm-mcp)
  7. </div>
  8. RubyLLM::MCP is a Ruby client for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), built to work cleanly with [RubyLLM](https://github.com/crmne/ruby_llm). Aiming to be completely spec compliant.
  9. Use MCP tools, resources, and prompts from your RubyLLM chats over `stdio`, streamable HTTP, or SSE.
  10. **Protocol support:** Fully supports MCP spec `2025-06-18` (stable), with draft spec `2026-01-26` available.
  11. ## RubyLLM::MCP Out of the Box
  12. Our goal is to be able to plug MCP into Ruby/RubyLLM apps as easily as possible.
  13. RubyLLM::MCP gives you that:
  14. - Ruby-first API for using MCP tools, resources, and prompts directly in RubyLLM chat workflows
  15. - Stable protocol track by default (`2025-06-18`), with opt-in draft track (`2026-01-26`)
  16. - Built-in notification and response handlers for real-time and interactive workflows
  17. - MCP OAuth 2.1 authentication support (PKCE, dynamic registration, discovery, and automatic token refresh)
  18. - OAuth setup paths for Rails apps (per-user connections) and browser-based CLI flows
  19. - Straightforward integration for any Ruby app, background job, or Rails project using RubyLLM
  20. ## Show me the code
  21. ```ruby
  22. # Basic setup
  23. require "ruby_llm/mcp"
  24. RubyLLM.configure do |config|
  25. config.openai_api_key = ENV.fetch("OPENAI_API_KEY")
  26. end
  27. client = RubyLLM::MCP.client(
  28. name: "filesystem",
  29. transport_type: :stdio,
  30. config: {
  31. command: "bunx",
  32. args: ["@modelcontextprotocol/server-filesystem", Dir.pwd]
  33. }
  34. )
  35. chat = RubyLLM.chat(model: "gpt-4.1-mini")
  36. chat.with_tools(*client.tools)
  37. puts chat.ask("Find Ruby files modified today and summarize what changed.")
  38. ```
  39. ```ruby
  40. # Resources
  41. resource = client.resource("release_notes")
  42. chat = RubyLLM.chat(model: "gpt-4.1-mini")
  43. chat.with_resource(resource)
  44. puts chat.ask("Summarize release notes for the team in 5 bullet points.")
  45. ```
  46. ```ruby
  47. # Prompts
  48. prompt = client.prompt("code_review")
  49. chat = RubyLLM.chat(model: "gpt-4.1-mini")
  50. response = chat.ask_prompt(
  51. prompt,
  52. arguments: {
  53. language: "ruby",
  54. focus: "security"
  55. }
  56. )
  57. puts response
  58. ```
  59. ```ruby
  60. # Handlers (response + notifications)
  61. client.on_progress do |progress|
  62. puts "Progress: #{progress.progress}% - #{progress.message}"
  63. end
  64. client.on_logging do |logging|
  65. puts "[#{logging.level}] #{logging.message}"
  66. end
  67. chat = RubyLLM.chat(model: "gpt-4.1-mini")
  68. chat.with_tools(*client.tools)
  69. chat.ask("Run a repository scan and summarize risks.") do |chunk|
  70. print chunk.content
  71. end
  72. ```
  73. ```ruby
  74. # OAuth setup (Rails and CLI)
  75. # Rails: per-user OAuth client (after running rails generate ruby_llm:mcp:oauth:install User)
  76. client = current_user.mcp_client
  77. chat = RubyLLM.chat(model: "gpt-4.1-mini")
  78. chat.with_tools(*client.tools)
  79. puts chat.ask("What changed in my connected repos this week?")
  80. # CLI: browser-based OAuth flow
  81. cli_client = RubyLLM::MCP.client(
  82. name: "oauth-server",
  83. transport_type: :streamable,
  84. start: false,
  85. config: {
  86. url: ENV.fetch("MCP_SERVER_URL"),
  87. oauth: { scope: "mcp:read mcp:write" }
  88. }
  89. )
  90. cli_client.oauth(type: :browser).authenticate
  91. cli_client.start
  92. puts RubyLLM.chat(model: "gpt-4.1-mini").with_tools(*cli_client.tools).ask("List my open tasks.")
  93. cli_client.stop
  94. ```
  95. ## Features
  96. - **Tools:** Convert MCP tools into RubyLLM-compatible tools
  97. - **Resources:** Work with resources and resource templates in chat context
  98. - **Prompts:** Execute server prompts with typed arguments
  99. - **Transports:** `:stdio`, `:streamable`, and `:sse`
  100. - **Client capabilities:** Sampling, roots, progress tracking, and elicitation
  101. - **Handlers:** Built-in notification and response handlers for real-time and interactive workflows
  102. - **MCP Authentication:** OAuth 2.1 support with PKCE, dynamic registration, discovery, and automatic token refresh
  103. - **OAuth setup paths:** Rails per-user OAuth setup and browser-based OAuth for CLI tools
  104. - **Extensions:** Global/per-client extension negotiation, including MCP Apps
  105. - **Multi-client support:** Manage multiple MCP servers in one workflow
  106. - **Protocol control:** Stable default with explicit draft opt-in
  107. - **Adapters:** Native `:ruby_llm` adapter (full feature set) and optional `:mcp_sdk`
  108. ## Installation
  109. Add to your Gemfile:
  110. ```ruby
  111. gem "ruby_llm-mcp"
  112. ```
  113. Then run:
  114. ```bash
  115. bundle install
  116. ```
  117. If you want the official SDK adapter, also add:
  118. ```ruby
  119. gem "mcp", "~> 0.7"
  120. ```
  121. ## Rails
  122. ```bash
  123. rails generate ruby_llm:mcp:install
  124. ```
  125. For OAuth-based user connections:
  126. ```bash
  127. rails generate ruby_llm:mcp:oauth:install User
  128. ```
  129. OAuth quick example:
  130. ```ruby
  131. client = RubyLLM::MCP.client(
  132. name: "oauth-server",
  133. transport_type: :streamable,
  134. start: false,
  135. config: {
  136. url: ENV.fetch("MCP_SERVER_URL"),
  137. oauth: { scope: "mcp:read mcp:write" }
  138. }
  139. )
  140. client.oauth(type: :browser).authenticate
  141. client.start
  142. chat = RubyLLM.chat(model: "gpt-4.1-mini")
  143. chat.with_tools(*client.tools)
  144. puts chat.ask("What should I prioritize today?")
  145. client.stop
  146. ```
  147. Then use explicit connection blocks in jobs/controllers/services:
  148. ```ruby
  149. RubyLLM::MCP.establish_connection do |clients|
  150. chat = RubyLLM.chat(model: "gpt-4.1-mini")
  151. chat.with_tools(*clients.tools)
  152. chat.ask("Analyze this pull request and list risks.")
  153. end
  154. ```
  155. ## Documentation
  156. - [rubyllm-mcp.com](https://rubyllm-mcp.com/)
  157. - [Getting Started](https://rubyllm-mcp.com/getting-started/getting-started.html)
  158. - [Rails Integration](https://rubyllm-mcp.com/guides/rails-integration.html)
  159. - [Adapters and transports](https://rubyllm-mcp.com/guides/adapters.html)
  160. ## Contributing
  161. Issues and pull requests are welcome at [patvice/ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp).
  162. ## License
  163. Released under the MIT License.

Ratings and comments

Sign in to rate this skill.

Sign in

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