ruby_llm-mcp

ruby_llm-mcp

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

Stars: 213

Visit
 screenshot

RubyLLM::MCP is a Ruby client for the Model Context Protocol (MCP), designed to seamlessly integrate with RubyLLM. It provides a Ruby-first API for using MCP tools, resources, and prompts directly in RubyLLM chat workflows. The tool supports the stable MCP spec `2025-06-18` and offers draft spec `2026-01-26` compatibility. It includes features like notification and response handlers, OAuth 2.1 authentication support, integration paths for Rails apps and CLI flows, and straightforward integration for any Ruby app or Rails project using RubyLLM. The tool allows users to work with MCP tools, resources, and prompts over `stdio`, streamable HTTP, or SSE transports.

README:

RubyLLM::MCP RubyLLM::MCP

MCP for Ruby and RubyLLM, as easy as possible.

Gem Version Gem Downloads

RubyLLM::MCP is a Ruby client for the Model Context Protocol (MCP), built to work cleanly with RubyLLM. Aiming to be completely spec compliant.

Use MCP tools, resources, and prompts from your RubyLLM chats over stdio, streamable HTTP, or SSE.

Protocol support: Fully supports MCP spec 2025-06-18 (stable), with draft spec 2026-01-26 available.

RubyLLM::MCP Out of the Box

Our goal is to be able to plug MCP into Ruby/RubyLLM apps as easily as possible.

RubyLLM::MCP gives you that:

  • Ruby-first API for using MCP tools, resources, and prompts directly in RubyLLM chat workflows
  • Stable protocol track by default (2025-06-18), with opt-in draft track (2026-01-26)
  • Built-in notification and response handlers for real-time and interactive workflows
  • MCP OAuth 2.1 authentication support (PKCE, dynamic registration, discovery, and automatic token refresh)
  • OAuth setup paths for Rails apps (per-user connections) and browser-based CLI flows
  • Straightforward integration for any Ruby app, background job, or Rails project using RubyLLM

Show me the code

# Basic setup
require "ruby_llm/mcp"

RubyLLM.configure do |config|
  config.openai_api_key = ENV.fetch("OPENAI_API_KEY")
end

client = RubyLLM::MCP.client(
  name: "filesystem",
  transport_type: :stdio,
  config: {
    command: "bunx",
    args: ["@modelcontextprotocol/server-filesystem", Dir.pwd]
  }
)

chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_tools(*client.tools)

puts chat.ask("Find Ruby files modified today and summarize what changed.")
# Resources
resource = client.resource("release_notes")
chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_resource(resource)

puts chat.ask("Summarize release notes for the team in 5 bullet points.")
# Prompts
prompt = client.prompt("code_review")
chat = RubyLLM.chat(model: "gpt-4.1-mini")

response = chat.ask_prompt(
  prompt,
  arguments: {
    language: "ruby",
    focus: "security"
  }
)

puts response
# Handlers (response + notifications)
client.on_progress do |progress|
  puts "Progress: #{progress.progress}% - #{progress.message}"
end

client.on_logging do |logging|
  puts "[#{logging.level}] #{logging.message}"
end

chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_tools(*client.tools)

chat.ask("Run a repository scan and summarize risks.") do |chunk|
  print chunk.content
end
# OAuth setup (Rails and CLI)
# Rails: per-user OAuth client (after running rails generate ruby_llm:mcp:oauth:install User)
client = current_user.mcp_client
chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_tools(*client.tools)
puts chat.ask("What changed in my connected repos this week?")

# CLI: browser-based OAuth flow
cli_client = RubyLLM::MCP.client(
  name: "oauth-server",
  transport_type: :streamable,
  start: false,
  config: {
    url: ENV.fetch("MCP_SERVER_URL"),
    oauth: { scope: "mcp:read mcp:write" }
  }
)

cli_client.oauth(type: :browser).authenticate
cli_client.start
puts RubyLLM.chat(model: "gpt-4.1-mini").with_tools(*cli_client.tools).ask("List my open tasks.")
cli_client.stop

Features

  • Tools: Convert MCP tools into RubyLLM-compatible tools
  • Resources: Work with resources and resource templates in chat context
  • Prompts: Execute server prompts with typed arguments
  • Transports: :stdio, :streamable, and :sse
  • Client capabilities: Sampling, roots, progress tracking, and elicitation
  • Handlers: Built-in notification and response handlers for real-time and interactive workflows
  • MCP Authentication: OAuth 2.1 support with PKCE, dynamic registration, discovery, and automatic token refresh
  • OAuth setup paths: Rails per-user OAuth setup and browser-based OAuth for CLI tools
  • Extensions: Global/per-client extension negotiation, including MCP Apps
  • Multi-client support: Manage multiple MCP servers in one workflow
  • Protocol control: Stable default with explicit draft opt-in
  • Adapters: Native :ruby_llm adapter (full feature set) and optional :mcp_sdk

Installation

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"

Rails

rails generate ruby_llm:mcp:install

For OAuth-based user connections:

rails generate ruby_llm:mcp:oauth:install User

OAuth quick example:

client = RubyLLM::MCP.client(
  name: "oauth-server",
  transport_type: :streamable,
  start: false,
  config: {
    url: ENV.fetch("MCP_SERVER_URL"),
    oauth: { scope: "mcp:read mcp:write" }
  }
)

client.oauth(type: :browser).authenticate
client.start

chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_tools(*client.tools)
puts chat.ask("What should I prioritize today?")

client.stop

Then use explicit connection blocks in jobs/controllers/services:

RubyLLM::MCP.establish_connection do |clients|
  chat = RubyLLM.chat(model: "gpt-4.1-mini")
  chat.with_tools(*clients.tools)
  chat.ask("Analyze this pull request and list risks.")
end

Documentation

Contributing

Issues and pull requests are welcome at patvice/ruby_llm-mcp.

License

Released under the MIT License.

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for ruby_llm-mcp

Similar Open Source Tools

For similar tasks

For similar jobs