mcp-oracledb
Production-ready Oracle MCP server with 55+ tools (Enhanced) / 75+ tools (Enterprise). Spring Boot 3.4.5, Spring AI 1.0.1, Oracle 11g-23c, Java 17.
claude mcp add --transport stdio officeworkplace-mcp-oracledb-server java -jar target/mcp-oracledb-server-1.0.0-PRODUCTION.jar \ --env MCP_TEST_MODE="false" \ --env MCP_TRANSPORT="stdio" \ --env SPRING_PROFILES_ACTIVE="production"
How to use
This MCP server exposes a comprehensive set of Oracle database operations via a production-ready MCP implementation built with Spring Boot. It leverages raw JDBC through Spring JDBC Template, enabling direct access to Oracle system views and enterprise features. The server can operate in standard MCP transport (stdio) with REST fallback for testing, and supports tools for database, schema, user, and table management, along with advanced analytics, AI-assisted operations, and enterprise capabilities like VPD, TDE, and partitioning. You can discover available tools, ping connectivity, and perform Oracle-specific tasks using the provided endpoints and tooling.
To interact with the server, connect to the REST endpoints or use the built-in tool discovery and execution flow. Typical workflows include listing available Oracle tools, checking connectivity (oracle_ping), and enumerating databases (oracle_list_databases). The server is designed to detect features dynamically and expose tools based on the configured edition (Enhanced or Enterprise). If you enable the REST mode, you can exercise the same operations via HTTP requests as you would via the standard MCP transport.
How to install
Prerequisites:
- Java 17+ (OpenJDK preferred)
- Maven 3.8+ (for building from source)
- Oracle Database 11g through 23c (or access to an Oracle instance)
- (Optional) Docker if you prefer containerized deployment
-
Clone the repository git clone https://github.com/officeWorkPlace/mcp-oracledb-server.git cd mcp-oracledb-server
-
Build the server (Enhanced Edition by default, 55+ tools) mvn clean package -Penhanced
-
Configure database connection
- Edit src/main/resources/application.properties to set: spring.datasource.url=jdbc:oracle:thin:@localhost:1521:XE spring.datasource.username=hr spring.datasource.password=password spring.datasource.driver-class-name=oracle.jdbc.OracleDriver
- Optionally adjust MCP configuration: mcp.tools.exposure=public mcp.transport=stdio
-
Run the server java -jar target/mcp-oracledb-server-1.0.0-PRODUCTION.jar (Alternatively, run in REST mode for testing) java -jar target/mcp-oracledb-server-1.0.0-PRODUCTION.jar --spring.profiles.active=rest
-
Test basic endpoints List tools: curl -X POST http://localhost:8080/v1/tools/list Ping connectivity: curl -X POST http://localhost:8080/v1/tools/oracle_ping List databases: curl -X POST http://localhost:8080/v1/tools/oracle_list_databases -H "Content-Type: application/json" -d '{"includePdbs": true}'
Additional notes
Tips and common considerations:
- Ensure Oracle JDBC driver is available on the classpath (configured in dependencies).
- Use application.properties to set Oracle connection details and MCP exposure level; these can also be overridden by environment variables if needed.
- For production deployments, consider enabling the Enterprise edition features (partitioning, AWR, Database Vault) and configuring security hardening (Spring Security, TLS termination, access controls).
- If you switch to REST mode for testing, remember to pass --spring.profiles.active=rest to run the jar in REST endpoints mode.
- When running via Docker, create an image with the JAR and dependencies, and expose port 8080 or your preferred port; adjust environment variables as needed for Oracle connectivity.
- Common troubleshooting: verify Oracle listener/tns entries, ensure correct JDBC URL format, and confirm that the required Oracle client libraries are present on the runtime.
