https://github.com/patvice/ruby_llm-mcp

Full-featured MCP support for Ruby and RubyLLM—making it easy to build structured, composable LLM workflows in pure Ruby.
https://github.com/patvice/ruby_llm-mcp

ai llms mcp mcp-clients rails ruby ruby-llm

Last synced: 3 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/patvice/ruby_llm-mcp
Owner: patvice
License: mit
Created: 2025-05-22T15:47:41.000Z (about 1 year ago)
Default Branch: main
Last Pushed: 2026-03-05T16:31:54.000Z (3 months ago)
Last Synced: 2026-03-05T19:31:39.375Z (3 months ago)
Topics: ai, llms, mcp, mcp-clients, rails, ruby, ruby-llm
Language: Ruby
Homepage: https://www.rubyllm-mcp.com/
Size: 13.4 MB
Stars: 228
Watchers: 4
Forks: 22
Open Issues: 4
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

          






MCP for Ruby and RubyLLM, as easy as possible.

[![Gem Version](https://badge.fury.io/rb/ruby_llm-mcp.svg)](https://badge.fury.io/rb/ruby_llm-mcp)

[![Gem Downloads](https://img.shields.io/gem/dt/ruby_llm-mcp)](https://rubygems.org/gems/ruby_llm-mcp)



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.

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

```ruby

# 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.")

```

```ruby

# 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.")

```

```ruby

# 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

```

```ruby

# 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

```

```ruby

# 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:

```ruby

gem "ruby_llm-mcp"

```

Then run:

```bash

bundle install

```

If you want the official SDK adapter, also add:

```ruby

gem "mcp", "~> 0.7"

```

## Rails

```bash

rails generate ruby_llm:mcp:install

```

For OAuth-based user connections:

```bash

rails generate ruby_llm:mcp:oauth:install User

```

OAuth quick example:

```ruby

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:

```ruby

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

- [rubyllm-mcp.com](https://rubyllm-mcp.com/)

- [Getting Started](https://rubyllm-mcp.com/getting-started/getting-started.html)

- [Rails Integration](https://rubyllm-mcp.com/guides/rails-integration.html)

- [Adapters and transports](https://rubyllm-mcp.com/guides/adapters.html)

## Contributing

Issues and pull requests are welcome at [patvice/ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp).

## License

Released under the MIT License.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/patvice/ruby_llm-mcp

Awesome Lists containing this project

README