ORMCP Server

Make your relational data AI ready

ORMCP Server is a Model Context Protocol (MCP) server that enables AI assistants to interact with relational databases using intuitive, object-oriented operations in JSON format.

What is ORMCP Server?

ORMCP Server bridges the gap between AI applications and relational databases. It leverages the Gilhari microservice framework and JDX ORM to provide seamless database access through the standardized MCP protocol.

Instead of writing SQL, AI assistants like Claude and Gemini can work with your data using natural language and high-level object operations.

Key Features

• 🌍 Database Agnostic - Works with any JDBC-compliant database (PostgreSQL, MySQL, Oracle, SQL Server, SQLite, etc.)
• ✅ MCP Compliant - Fully compatible with the Model Context Protocol standard
• 🔄 Object-Relational Mapping - JSON object operations transparently mapped to relational data
• 🧾 Declarative ORM - Define mappings using simple JDX grammar
• 🚀 High Performance - Optimized with connection pooling, caching, and minimal database trips
• 🔒 Secure - Domain model-specific operations with optional read-only mode

Quick Start

Installation

pip install ormcp-server

If you have an existing Gemfury token from an earlier beta install, it will no longer work — Gemfury access has been discontinued. Use pip install ormcp-server above, which installs from public PyPI directly.

Accessing Full Package with SDK and Examples

The source distribution includes everything you need to get started beyond the installable package itself — a curated subset of the Gilhari SDK and a ready-to-use example microservice.

# Download source distribution from PyPI
pip download --no-binary :all: ormcp-server

# Extract it (use the appropriate version number)
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

# Now you have access to:
# - Gilhari_SDK/          Gilhari SDK essentials (libs, config, docs)
#                         Note: JDX User Manual excluded due to size; available at
#                         https://www.softwaretree.com/v1/products/jdx/docs/JDX-5.0-Manual-v1.pdf
# - gilhari_example1/     Ready-to-use SQLite-backed example microservice
# - package/client/       Example MCP client code
# - package/docs/         Additional ORMCP documentation

Basic Usage

1. Configure and start your Gilhari microservice (handles database connectivity)
2. Configure ORMCP Server:

# Linux/macOS
export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
export MCP_SERVER_NAME="MyORMCPServer"

# Windows (Command Prompt)
set GILHARI_BASE_URL=http://localhost:80/gilhari/v1/
set MCP_SERVER_NAME=MyORMCPServer

GILHARI_BASE_URL must use the port your Gilhari microservice listens on (for a Docker container, the host port shown by docker ps). It is the only Gilhari setting you need: ORMCP checks that a microservice answers there when it starts, and otherwise stops with a message naming the address it checked and what to do.

3. Start the server:

ormcp-server

4. Connect your AI client (e.g., Claude Desktop):

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "ormcp-server",
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

How It Works

AI Assistant <--MCP--> ORMCP Server <--REST--> Gilhari Microservice <--JDBC--> Database

1. User sends natural language request to AI assistant (e.g., Claude)
2. AI assistant translates natural language into MCP tool calls
3. ORMCP Server receives MCP tool calls and translates to REST API calls
4. Gilhari microservice executes database operations via JDBC/SQL
5. Results returned as JSON objects through the chain back to user

Example Interactions

Query data:

"Show me all users in California"
"What's the average age of users?"

Manage data:

"Create a new user named John Smith in Boston"
"Update all users in New York to have status=active"

Explore schema:

"What types of objects are available?"
"Show me the attributes of the User class"

Available MCP Tools

• getObjectModelSummary - Discover classes and relationships
• query - Retrieve objects with filtering and sorting
• getObjectById - Fetch specific objects by primary key
• access - Navigate object relationships
• getAggregate - Calculate COUNT, SUM, AVG, MIN, MAX
• insert - Create new objects
• update - Update existing objects
• update2 - Bulk-update existing objects
• delete - Delete objects
• delete2 - Bulk-delete existing objects

Read-only by default: READONLY_MODE defaults to true, so the insert/update/update2/delete/delete2 tools are not available unless you set READONLY_MODE=false.

Configuration

ORMCP Server is configured with environment variables. The most common ones:

See the complete documentation for all settings, including HTTP mode.

Requirements

• Python 3.12+
• Docker (for Gilhari microservice)
• JDBC driver for your database
• MCP-compatible client (Claude Desktop, Gemini CLI, etc.)

Documentation

• Complete Documentation: github.com/softwaretree/ormcp-docs
• API Reference: ORMCP Tools Reference
• Quick Start: Getting Started Guide
• GitHub repositories with working examples: Browse Examples
• Example Microservice: github.com/SoftwareTree/gilhari_example1

Beta Notice

ORMCP Server is currently in Beta for testing and evaluation purposes only. Not intended for commercial use.

Support

• Email: ormcp_support@softwaretree.com
• Issues: github.com/softwaretree/ormcp-docs/issues
• Website: softwaretree.com

License

Proprietary software owned by Software Tree, LLC. See LICENSE for terms.

Beta Evaluation: Free for testing and evaluation for 30 days from the date of installation.

Commercial licensing: Use of ORMCP Server beyond the evaluation period is subject to then-applicable Software Tree licensing terms. For information or to express interest, contact Software Tree at ormcp_support@softwaretree.com or visit https://www.softwaretree.com.

Software Tree | Making databases AI-accessible