π Interactive Oracle Database Explorer with AI-powered MCP Integration
β¨ Interactive TUI - Modern terminal interface with full keyboard navigation
π Schema Explorer - Browse tables, packages, procedures, and functions
π Multi-Schema Support - Easy switching between schemas with dropdown selector
π Data Preview - View table structures and sample data
πΎ SQL Editor - Execute custom SQL queries with Ctrl+E and instant results
π Smart Search - Real-time filtering with Ctrl+S across all objects
β‘ Lightning Fast - Intelligent caching & prefetching for instant navigation
π Smart Performance - Background loading & 5-minute cache for large databases
π Copy to Clipboard - Export table structure & data in markdown format with Ctrl+Y
π€ AI-Ready - Perfect for pasting into ChatGPT, Claude, Cursor, or any AI assistant
π¨ Syntax Highlighting - Color-coded PL/SQL source code viewer
π¨ Theme Toggle - Switch between light and dark themes via Command Palette (Ctrl+P)
β¨οΈ Keyboard First - Navigate everything with arrow keys, no mouse needed
π No Client Required - Uses python-oracledb thin mode by default
π MCP Server - Integrates with AI tools (Cursor, VS Code, Claude) via Model Context Protocol
π Relationship Discovery - Automatically find foreign key relationships between tables
π Performance Analysis - Index analysis and optimization recommendations
π Constraint Mapping - Complete view of primary keys, foreign keys, unique constraints
Oracle-CLI now works as an MCP server! Let AI assistants directly access your Oracle database.
pipx install git+https://github.com/oguzhankalelioglu/oracle-cli.gitoracle-cli configureOption 1: One-Click Install (Easiest!)
Click the button above β Cursor will automatically add the configuration!
Option 2: Manual Configuration
Open Cursor Settings β Features β Model Context Protocol β Add this JSON:
For macOS/Linux:
{
"mcpServers": {
"oracle-cli": {
"command": "oracle-cli",
"args": ["mcp"]
}
}
}For Windows:
First, find your Python path:
where pythonThen use one of these configurations:
Option A: Using Python directly (Recommended for Windows)
{
"mcpServers": {
"oracle-cli": {
"command": "python",
"args": ["-m", "oracle_cli", "mcp"]
}
}
}Option B: Using full path to oracle-cli
{
"mcpServers": {
"oracle-cli": {
"command": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\oracle-cli.exe",
"args": ["mcp"]
}
}
}π‘ Tip: Replace
YourUsernameandPython312with your actual paths
Ask your AI assistant:
- "List all tables in my database"
- "Show me the structure of EMPLOYEES table"
- "Find all customers from California"
- "What tables are related to EMPLOYEES?" π
- "Show me the indexes on EMPLOYEES table" π
- "Search for all tables containing 'customer'" π
That's it! π AI can now:
- β Query your Oracle database automatically
- β Discover table relationships and foreign keys
- β Analyze indexes and constraints
- β Search across your entire schema
- β Provide performance optimization tips
π‘ Works with: Cursor, VS Code, Claude Desktop, and any MCP-compatible AI tool
- Python 3.10 or higher
- Oracle Database (tested with 11g, 12c, 18c, 19c, 21c, 23c)
pipx install git+https://github.com/oguzhankalelioglu/oracle-cli.gitβΉοΈ If the
oracle-clicommand is not found in a new terminal session, runpipx ensurepath, restart your terminal, and make sure~/.local/binis on yourPATH.
pip install git+https://github.com/oguzhankalelioglu/oracle-cli.gitgit clone https://github.com/oguzhankalelioglu/oracle-cli.git
cd oracle-cli
pip install -e .pipx upgrade oracle-cliOr reinstall from GitHub for the latest version:
pipx uninstall oracle-cli
pipx install git+https://github.com/oguzhankalelioglu/oracle-cli.gitpip install --upgrade git+https://github.com/oguzhankalelioglu/oracle-cli.gitcd oracle-cli
git pull
pip install -e . --upgradeAfter updating:
- Configuration file (
~/.oracle_cli/config.json) is preserved - Cache is automatically cleared on first run
- Press
Rin TUI to clear cache and see new features
Save your Oracle connection details:
oracle-cli configureYou'll be prompted for:
- Username: Your Oracle database username
- Password: Your database password
- DSN: Connection string (e.g.,
localhost:1521/XEPDB1orhostname:1521/ORCL) - Schema: Default schema to explore (defaults to username)
oracle-cliThat's it! The interactive TUI will open.
Launch the full-featured terminal interface:
oracle-cli
# or explicitly
oracle-cli tui| Key | Action |
|---|---|
| β/β Arrows | Navigate through objects |
| Tab | Switch focus between panels |
| Ctrl+Y | π Copy selected object to clipboard (markdown format) |
| Ctrl+S | Toggle search (real-time filtering) |
| Ctrl+P | Open command palette (schema, theme, etc.) |
| Ctrl+Shift+P | Show procedures only |
| Ctrl+K | Show packages only |
| Ctrl+E | Open SQL editor (execute queries) |
| F1 | Show About/Help screen |
| R | Refresh & clear cache |
| ESC | Close panels/Cancel |
| Q | Quit application |
Press Ctrl+Y on any selected object to copy:
- Tables: Complete structure + sample data in markdown tables
- PL/SQL Objects: Full source code in code blocks
Perfect for:
- Asking AI to explain table structures
- Getting AI help with PL/SQL code
- Generating queries based on table schema
- Database documentation
Example workflow:
- Open
oracle-cliin your terminal - Navigate to a table using β/β arrows
- Press Ctrl+Y to copy
- Paste into ChatGPT/Claude/Cursor and ask: "Explain this table structure"
Press Ctrl+P to open the command palette for quick actions:
- Change Schema: Switch between database schemas
- Change Theme: Toggle between light and dark themes
- SQL Editor: Open SQL query editor
- Refresh: Clear cache and reload objects
- About: Show help and keyboard shortcuts
You can also use oracle-cli as a traditional CLI tool:
# List all tables
oracle-cli list-tables
# Describe table structure
oracle-cli describe-table EMPLOYEES
# Preview table data
oracle-cli preview-table EMPLOYEES --limit 10
# List packages
oracle-cli list-packages --with-body
# List procedures
oracle-cli list-programs --type procedure
# Show PL/SQL source code
oracle-cli show-source MY_PACKAGE --type package
# Show package body
oracle-cli show-source MY_PACKAGE --type package --body
# Switch schema
oracle-cli use-schema HRexport ORACLE_USER=hr
export ORACLE_PASSWORD='your_password'
export ORACLE_DSN='localhost:1521/XEPDB1'
export ORACLE_SCHEMA='HR' # Optional
oracle-clioracle-cli --user hr --password secret --dsn localhost:1521/XEPDB1 --schema HRConnection details are stored in ~/.oracle_cli/config.json. You can:
- Update configuration:
oracle-cli configure - Use custom path:
oracle-cli configure --path /custom/path/config.json
Note: Configuration file may contain sensitive information. Never commit it to version control.
Oracle-CLI is optimized for large databases with thousands of tables:
- Intelligent Cache: Table structures and data are cached for 5 minutes
- Instant Navigation: Second visit to a table is instant (from cache)
- Auto-Refresh: Press R to clear cache and reload
- Schema-Aware: Changing schemas automatically clears cache
- Predictive Loading: Next 2-3 tables are loaded in background
- Seamless Experience: By the time you navigate, data is ready
- Smart Queue: Only prefetches items you're likely to visit
# For very large databases (10,000+ tables)
oracle-cli tui --limit 20 # Reduce data preview rows
# Enable debug mode to see cache hits
oracle-cli tui --debug
# Check cache statistics
# Open TUI, press F1 (About) - shows cache countPerformance Improvements:
- β First table load: ~200-500ms
- β Cached table load: <50ms (4-10x faster!)
- β Prefetched table: Instant (already loaded)
By default, python-oracledb runs in thin mode (no Oracle Client required).
If your organization requires Oracle Instant Client:
- Install Oracle Instant Client
- Set the
ORACLE_CLIENT_LIB_DIRenvironment variable - The tool will automatically use thick mode
# Clone repository
git clone https://github.com/oguzhankalelioglu/oracle-cli.git
cd oracle-cli
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install in development mode
pip install -e .
# Install development dependencies
pip install -e ".[dev]"oracle-cli/
βββ oracle_cli/
β βββ __init__.py
β βββ __main__.py
β βββ cli.py # CLI commands
β βββ config.py # Configuration management
β βββ db.py # Database operations
β βββ tui.py # Text User Interface
βββ pyproject.toml # Project metadata
βββ README.md
βββ LICENSE
βββ INSTALL.md
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
OΔuzhan KalelioΔlu
- GitHub: @oguzhankalelioglu
- Built with Textual - An amazing TUI framework
- Uses python-oracledb - Oracle's official Python driver
- CLI powered by Click
- Pretty output by Rich
- β 13 Powerful Tools: List tables, describe structures, query data, analyze relationships
- π Secure: SELECT-only queries, local stdio access
- β‘ Fast: Uses existing caching system
- π― Smart: AI automatically selects the right tools
- π Relational: Discover table relationships and dependencies
- π Analytical: Index analysis, constraint mapping, performance insights
| Tool | Description |
|---|---|
list_tables |
List all tables in the schema |
describe_table |
View detailed table structure (columns, types, constraints) |
query_table |
Get sample data from a table |
get_table_stats |
Get table statistics (row count, size, segments) |
| Tool | Description |
|---|---|
get_table_relationships |
View foreign key relationships (parent & child tables) |
get_table_constraints |
Show all constraints (PRIMARY KEY, FOREIGN KEY, UNIQUE, CHECK) |
get_related_tables |
Find all related tables through foreign key relationships |
get_table_indexes |
List all indexes with performance insights |
| Tool | Description |
|---|---|
search_tables |
Search tables and columns by keyword across schema |
| Tool | Description |
|---|---|
execute_sql |
Run custom SELECT queries (read-only) |
get_table_triggers |
List table triggers with event details |
list_objects |
List PL/SQL packages, procedures, functions |
get_source |
View PL/SQL source code |
For detailed setup and troubleshooting: MCP_SETUP.md
- Copy to clipboard (markdown format) β
- Full keyboard navigation β
- MCP Server Integration β
- Table relationships viewer β
- Index and constraint viewer β
- Advanced schema analysis β
- SQL Editor with real-time execution β
- Multi-schema switching β
- Search and filtering β
- Theme toggle (light/dark) β
- Command Palette β
- Export data to CSV/JSON
- Save and load SQL queries
- Query history
- Support for database diagrams
- Multi-connection management
- Plugin system
- ER diagram visualization
- Performance monitoring dashboard
If you encounter any issues or have questions:
- π« Open an issue
- π¬ Start a discussion
Note: This tool is designed for development and database exploration. Always follow your organization's security policies when connecting to production databases.
