MCP Client for Crystal

A generic, reusable Model Context Protocol (MCP) client library for Crystal that enables Crystal applications to connect to MCP servers and use their capabilities.

Installation

Add this to your application's shard.yml:

dependencies:
  mcp-client:
    github: ralsina/mcp-client

Usage

Basic Example

require "mcp-client"

# Create a client with STDIO transport
client = MCP::Client.new("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"])

# Connect to the server
server_info = client.connect
puts "Connected to #{server_info.name} v#{server_info.version}"

# List available tools
tools = client.list_tools
tools.each do |tool|
  puts "#{tool.name}: #{tool.description}"
end

# Call a tool
result = client.call_tool("read_file", {"path" => JSON::Any.new("/path/to/file.txt")})
puts result.content.first["text"]?.try(&.as_s)

# Disconnect when done
client.disconnect

Using Custom Transport

require "mcp-client"

# Create a custom transport
class MyTransport < MCP::Transport
  def connect : Nil
    # Your connection logic
  end

  def disconnect : Nil
    # Your disconnect logic
  end

  def send_message(message : String) : Nil
    # Your send logic
  end

  def receive_message : String?
    # Your receive logic
  end

  def connected? : Bool
    # Your connection status
  end
end

# Use custom transport
transport = MyTransport.new
client_info = MCP::ClientInfo.new("my-client", "1.0.0")
client = MCP::Client.new(transport, client_info)

Checking Capabilities

client = MCP::Client.new("npx", ["-y", "@modelcontextprotocol/server-example"])
client.connect

# Check what the server supports
if client.supports_tools?
  puts "Server supports tools"
end

if client.supports_resources?
  puts "Server supports resources"
end

# Get full capabilities object
caps = client.server_capabilities

API Reference

MCP::Client

The main client class for communicating with MCP servers.

Constructors

• new(command : String, args : Array(String)) - Create client with STDIO transport
• new(transport : Transport, client_info : ClientInfo) - Create client with custom transport

Methods

• connect : ServerInfo - Connect and perform initialization handshake
• disconnect : Nil - Disconnect from the server
• connected? : Bool - Check if currently connected
• list_tools : Array(Tool) - List available tools
• call_tool(name, arguments) : ToolCallResult - Call a tool with arguments
• ping : Bool - Ping the server to check connectivity
• server_capabilities : ServerCapabilities? - Get server capabilities
• supports_tools? : Bool - Check if server supports tools
• supports_resources? : Bool - Check if server supports resources
• supports_prompts? : Bool - Check if server supports prompts

Types

• MCP::ClientInfo - Client identification (name, version)
• MCP::ServerInfo - Server information (name, version)
• MCP::Tool - Tool definition (name, description, input_schema)
• MCP::ToolCallResult - Result of calling a tool
• MCP::Error - Error response from server
• MCP::ServerCapabilities - Server capabilities

Exceptions

• MCP::MCPError - Base exception for MCP errors
• MCP::MCPConnectionError - Connection-related errors
• MCP::MCPProtocolError - Protocol-related errors
• MCP::MCPToolError - Tool call errors

Development

Running Tests

crystal spec

Building

shards build

Running Examples

# Basic example
./bin/basic_tool_client /tmp

# Advanced example
./bin/advanced_usage /tmp

Project Status

This is currently in development. The initial version supports:

• [x] STDIO transport
• [x] Tool listing and calling
• [x] Basic capability negotiation
• [x] Error handling

Planned for future versions:

• [ ] HTTP/SSE transport
• [ ] Resources support
• [ ] Prompts support
• [ ] Logging configuration
• [ ] Progress token support
• [ ] Request cancellation

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

MIT License - see LICENSE file for details.