bioruby-mcp-server

A Model Context Protocol (MCP) server that provides access to BioRuby KEGG functionality. This server allows AI assistants to query KEGG databases for biological pathways, compounds, enzymes, and other molecular information through the standardized MCP protocol.

Built using the official MCP Ruby SDK.

Add this line to your application's Gemfile:

gem 'bioruby-mcp-server'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install bioruby-mcp-server

To start the MCP server:

$ bioruby-mcp-server

The server will start and listen for MCP protocol messages on stdin/stdout.

The server provides the following tools for interacting with KEGG databases:

Get detailed information about a KEGG pathway.

Parameters:

• pathway_id (string): KEGG pathway ID (e.g., 'map00010', 'hsa00010')

Example:

{
  "name": "kegg_pathway_info",
  "arguments": {
    "pathway_id": "map00010"
  }
}

Get detailed information about a KEGG compound.

Parameters:

• compound_id (string): KEGG compound ID (e.g., 'C00002', 'cpd:C00002')

Example:

{
  "name": "kegg_compound_info",
  "arguments": {
    "compound_id": "C00002"
  }
}

Get detailed information about a KEGG enzyme.

Parameters:

• enzyme_id (string): KEGG enzyme ID (e.g., 'ec:1.1.1.1')

Example:

{
  "name": "kegg_enzyme_info",
  "arguments": {
    "enzyme_id": "ec:1.1.1.1"
  }
}

Search for KEGG compounds by name or formula.

Parameters:

• query (string): Search query (compound name, formula, etc.)
• database (string, optional): Database to search (default: 'compound')

Example:

{
  "name": "kegg_search_compounds",
  "arguments": {
    "query": "glucose",
    "database": "compound"
  }
}

Find pathways containing a specific compound.

Parameters:

• compound_id (string): KEGG compound ID (e.g., 'C00002')

Example:

{
  "name": "kegg_find_pathways_by_compound",
  "arguments": {
    "compound_id": "C00002"
  }
}

List available organisms in KEGG.

Parameters:

• filter (string, optional): Optional filter for organism names

Example:

{
  "name": "kegg_list_organisms",
  "arguments": {
    "filter": "human"
  }
}

This MCP server can be used with any AI assistant that supports the Model Context Protocol. Configure your AI assistant to connect to this server to enable KEGG database queries.

To connect this server to Claude Desktop, you'll need to configure it in Claude's MCP settings:

First, install the bioruby-mcp-server gem:

gem install bioruby-mcp-server

Add the server configuration to Claude Desktop's configuration file:

On macOS: Edit or create ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: Edit or create %APPDATA%\Claude\claude_desktop_config.json

On Linux: Edit or create ~/.config/Claude/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "bioruby-kegg": {
      "command": "bioruby-mcp-server",
      "args": []
    }
  }
}

If you are Windows WSL user:

{
  "mcpServers": {
    "bioruby-kegg": {
			"command": "wsl.exe",
			"args": [
				"bioruby-mcp-server"
			]
    }
  }
}

After saving the configuration file, restart Claude Desktop to load the new MCP server.

Once connected, you can test the integration by asking Claude to query KEGG databases. For example:

• "Get information about KEGG pathway map00010"
• "Search for glucose compounds in KEGG"
• "Find pathways containing compound C00002"

If the connection fails:

1. Check gem installation: Ensure bioruby-mcp-server is installed and accessible in your PATH

   which bioruby-mcp-server
   gem list bioruby-mcp-server

2. Verify configuration: Check that the JSON configuration file is valid and in the correct location

3. Check permissions: Ensure Claude Desktop has permission to execute the bioruby-mcp-server command

4. Review logs: Check Claude Desktop's logs for any error messages related to MCP server connections

For other AI assistants that support MCP, use this general configuration format:

{
  "mcpServers": {
    "bioruby-kegg": {
      "command": "bioruby-mcp-server",
      "args": []
    }
  }
}

After checking out the repo, run bundle install to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Run the test suite:

$ bundle exec rake test

Run RuboCop for code style checking:

$ bundle exec rubocop

• Ruby 3.0 or higher
• Internet connectivity for accessing KEGG REST API

• bio - BioRuby library for biological data processing
• mcp - Official MCP Ruby SDK

This server is built using the official MCP Ruby SDK, ensuring full compliance with the Model Context Protocol specification. Each KEGG tool is implemented as an MCP::Tool subclass, providing proper input schema validation and structured responses.

• KEGG REST API Integration: Direct integration with KEGG's REST API for real-time data access
• BioRuby Parser Integration: Uses BioRuby's KEGG parsers for proper data structure handling
• MCP Protocol Compliance: Built on the official MCP Ruby SDK for standardized protocol handling
• Tool-based Architecture: Each KEGG operation is implemented as a separate MCP tool
• Robust Error Handling: Comprehensive error handling for network issues, invalid IDs, and API failures

Bug reports and pull requests are welcome on GitHub at https://github.com/kozo2/bioruby-mcp-server. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the BSD 2-Clause License.

Everyone interacting in the bioruby-mcp-server project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.