U2 MCP Server

Install

Config snippet generator goes here (5 client tabs)

README

# u2-mcp

[![PyPI version](https://img.shields.io/pypi/v/u2-mcp.svg)](https://pypi.org/project/u2-mcp/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io)

<!-- mcp-name: io.github.bpamiri/u2-mcp -->

**Connect Claude to your Universe/UniData database using natural language.**

u2-mcp is an MCP server that lets AI assistants like Claude query and interact with Rocket Universe and UniData MultiValue databases. Ask questions in plain English and get real answers from your data.

**The first MCP server for the Pick/MultiValue database family.**

## What Can You Do With This?

Instead of writing RetrieVe queries, just ask Claude:

| You Ask | Claude Does |
|---------|-------------|
| "How many customers are in California?" | Queries the database and tells you "1,247 customers" |
| "Show me order ORD001" | Reads the record and displays all fields |
| "What files are available?" | Lists all files in your account |
| "Describe the CUSTOMERS file" | Shows field definitions from the dictionary |

## How It Works

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop │◄───►│     u2-mcp      │◄───►│ Universe/UniData│
│  (You ask here) │     │  (Translates)   │     │   (Your data)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
```

1. You ask Claude a question about your database
2. Claude calls u2-mcp with the appropriate tool
3. u2-mcp queries your Universe/UniData server
4. Results come back through Claude in a readable format

**New to MCP?** See [What is MCP?](docs/what-is-mcp.md) for a complete explanation.

## Documentation

| Guide | Description |
|-------|-------------|
| [What is MCP?](docs/what-is-mcp.md) | Understanding MCP and how u2-mcp works |
| [Installation](docs/installation.md) | Complete installation guide |
| [Quickstart](docs/quickstart.md) | Get running in 10 minutes |
| [Configuration](docs/configuration.md) | All configuration options |
| [Tools Reference](docs/tools.md) | Detailed tool documentation |
| [Usage Examples](docs/examples.md) | Common usage patterns |
| [OAuth Setup](docs/oauth.md) | Claude.ai integration with SSO |

## Features

- **Connection Management** - Connect to Universe/UniData servers with connection pooling and SSL support
- **File Operations** - Read, write, and delete records while preserving MultiValue semantics
- **Query Execution** - Run RetrieVe/UniQuery statements with safety controls
- **Dictionary Access** - Explore file structures and field definitions
- **BASIC Subroutine Calls** - Execute cataloged BASIC programs
- **Transaction Support** - Full transaction management with commit/rollback
- **AI-Optimized** - Built-in query examples and syntax help for better LLM interactions

## Installation

```bash
pip install u2-mcp
```

Or using `uvx` for isolated execution:

```bash
uvx u2-mcp
```

## Quick Start

### Prerequisites

- Python 3.10+
- Access to a Rocket Universe or UniData server
- The `uopy` package (installed automatically as a dependency)

### Configuration

Set environment variables for your database connection:

```bash
export U2_HOST=server.example.com
export U2_USER=username
export U2_PASSWORD=password
export U2_ACCOUNT=MYACCOUNT
export U2_SERVICE=uvcs  # or 'udcs' for UniData
```

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "u2": {
      "command": "uvx",
      "args": ["u2-mcp"],
      "env": {
        "U2_HOST": "server.example.com",
        "U2_USER": "user",
        "U2_PASSWORD": "password",
        "U2_ACCOUNT": "MYACCOUNT"
      }
    }
  }
}
```

## Usage Examples

Once connected, you can use natural language to interact with your Universe database:

- "List all customers in California"
- "Read record CUST001 from the CUSTOMERS file"
- "Show me the dictionary for the ORDERS file"
- "Count all open invoices over $1000"

## Available Tools

### Connection Management
- `connect` - Establish connection to Universe/UniData server
- `disconnect` - Close connections
- `list_connections` - Show active connections

### File Operations
- `list_files` - List available files in the account
- `read_record` - Read a single record by ID
- `read_records` - Read multiple records
- `write_record` - Write/update a record
- `delete_record` - Delete a record
- `get_file_info` - Get file statistics

### Query Execution
- `execute_query` - Run RetrieVe/UniQuery statements
- `execute_tcl` - Run TCL/ECL commands
- `get_select_list` - Execute SELECT and return record IDs

### Dictionary Access
- `list_dictionary` - List dictionary items
- `get_field_definition` - Get field details
- `describe_file` - High-level file description

### Advanced Features
- `call_subroutine` - Call