Oracle MCP Server

🚀 Oracle MCP Server

An implementation of the Model Context Protocol (MCP) service for Oracle database operations based on spring-ai-mcp-server-webmvc-spring-boot-starter. This service provides a set of tools for interacting with Oracle databases via the MCP protocol and enables real-time communication using Server-Sent Events (SSE).

🚀 Quick Start

Prerequisites

• JDK 17
• Maven 3.6+
• An Oracle database instance
• MCP server environment
• Cursor IDE

Configuration

1. Database Configuration

Create or modify application.properties or application.yml and add the following settings:

oracle:
  connectionString: jdbc:oracle:thin:@//your-oracle-host:1521/your-service-name
  username: your-username
  password: your-password

2. Cursor MCP Configuration

Configure the MCP server settings in your Cursor IDE:

{
  "mcpServers": {
    "oracle-mcp-server": {
      "url": "http://{server-ip}:{server-port}/sse",
      "enabled": true
    }
  }
}

This configuration:

• Sets the MCP server name to "oracle-mcp-server".
• Configures the server URL as "http://{server-ip}:{server-port}/sse".
  • Replace {server-ip} with the IP address of your server.
  • Replace {server-port} with the port number of your server.
• Enables the MCP server for use in Cursor.

Build the Project

mvn clean install

Run the Application

mvn spring-boot:run

✨ Features

• List all tables in the Oracle database.
• Describe table structures (columns, data types, constraints).
• Execute SQL statements (SELECT, INSERT, UPDATE, DELETE).
• Secure database connection management.
• Real-time communication via SSE.
• Built on spring-ai-mcp-server-webmvc-spring-boot-starter.

📦 Installation

The installation steps are included in the "Quick Start" section above.

💻 Usage Examples

Basic Usage

The usage examples are demonstrated through the API tools described below.

📚 Documentation

API Tools

1. List Tables Tool

• Name: list_tables
• Description: Get a list of all tables in the Oracle database.
• Usage: No parameters required.
• Return Value: A list of table names separated by newlines.

2. Describe Table Tool

• Name: describe_table
• Description: Get the structure information of a specified table.
• Parameters: table_name
• Return Value: Detailed table information, including columns, data types, and constraints.

3. Execute SQL Statement Tool

• Name: execute_query
• Description: Execute any SQL query or update operation.
• Parameters: query_string
• Return Value: The query result set or operation status.

Implementation Details

Class Structure

The core code of the project is located in the oracle-mcp-server/src/main/java directory and mainly includes the following classes:

• OracleMCPHandler.java: Handles MCP protocol requests and responses.
• DatabaseManager.java: Manages database connections and operations.
• TableInfoCollector.java: Collects table structure information.
• QueryExecutor.java: Executes SQL queries and updates.

Functional Components

1. MCP Request Handling:
   • Parses MCP protocol requests.
   • Validates the legitimacy of requests.
   • Invokes corresponding functional modules for processing.
2. Database Connection Management:
   • Establishes connections with the Oracle database.
   • Manages the connection pool.
   • Handles the connection lifecycle.
3. Table Structure Information Collection:
   • Retrieves metadata of specified tables.
   • Parses column information.
   • Returns structured results.
4. SQL Execution Engine:
   • Analyzes and executes SQL statements.
   • Handles result sets.
   • Manages transactions and error handling.

Security Considerations

• The database connection string is stored encrypted.
• User credentials are securely hashed.
• Access Control Lists (ACL) are managed.
• All sensitive operations are logged.
• Defends against SQL injection attacks.

Testing

The project provides a complete set of unit tests and integration tests that cover all major functional modules. The test cases include:

• Successful and failed database connection scenarios.
• Execution of different types of SQL queries.
• Accuracy of table structure information collection.
• Effectiveness of security mechanisms.
• Handling of boundary conditions.

Error Handling

The system adopts a hierarchical error handling architecture with the following functions:

• Request validation and parameter checking.
• Exception capture and encapsulation.
• Error logging.
• User-friendly error responses.
• Transaction rollback mechanism.

Contribution Guidelines

Contributions to the code or issue reports from the community are welcome. Please refer to the CONTRIBUTING.md file in the project repository for the detailed contribution process.

🔧 Technical Details

The technical details are described in the "Implementation Details" section above.

📄 License

The project follows the Apache License 2.0. You can view the specific content in the LICENSE file.