Metadata-Version: 2.4
Name: mcp-oracle
Version: 0.1.1
Summary: MCP server for Oracle databases — thin mode, no Instant Client required
Project-URL: Repository, https://github.com/leonardocrdso/mcp-oracle
Project-URL: Issues, https://github.com/leonardocrdso/mcp-oracle/issues
Author-email: Leonardo Cardoso <leonardocrdso@gmail.com>
License: MIT
Keywords: claude,database,llm,mcp,oracle
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: mcp
Requires-Dist: oracledb
Description-Content-Type: text/markdown

# mcp-oracle

Oracle database MCP server using `python-oracledb` in thin mode — no Oracle Instant Client required.

## Installation

No manual installation needed. Run directly with:

```bash
uvx mcp-oracle
```

## Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "oracle": {
      "command": "uvx",
      "args": ["mcp-oracle"],
      "env": {
        "ORACLE_DSN": "host:1521/service_name",
        "ORACLE_USER": "usuario",
        "ORACLE_PASSWORD": "senha"
      }
    }
  }
}
```

## DSN Format

| Format | Example | Use when |
|--------|---------|----------|
| `host:port/service_name` | `db.example.com:1521/ORCL` | Most modern Oracle databases |
| `host:port:SID` | `db.example.com:1521:ORCL` | Legacy SID-based connections |

**service_name vs SID:** Modern Oracle databases use service names (check with your DBA). Use the `/` separator for service names and the `:` separator for SIDs.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ORACLE_DSN` | Yes | — | Database connection string |
| `ORACLE_USER` | Yes | — | Database username |
| `ORACLE_PASSWORD` | Yes | — | Database password |
| `ORACLE_QUERY_ROW_LIMIT` | No | 1000 | Maximum rows returned per query |
| `ORACLE_QUERY_TIMEOUT_SECONDS` | No | 30 | Query timeout in seconds |
| `ORACLE_POOL_MIN` | No | 1 | Minimum connection pool size |
| `ORACLE_POOL_MAX` | No | 4 | Maximum connection pool size |

## Available Tools

- **`list_tables`** — List tables and views accessible to the connected user. Pass `schema` to list objects from another schema.
- **`describe_table`** — Return columns, data types, nullability, and primary keys for a table. Pass `schema` for cross-schema lookups.
- **`run_query`** — Execute a `SELECT` statement and return results as JSON. Supports bind parameters via the `params` argument.

## Table Name Case Sensitivity

Oracle stores identifiers in uppercase by default. `describe_table("employees")` and `describe_table("EMPLOYEES")` are equivalent — the server normalizes to uppercase automatically.

## License

MIT — © Leonardo Cardoso
