Skip to main content
This guide covers setting up your local development environment to build, test, and contribute to Oracle MCP servers.

​
Prerequisites

Before starting local development, ensure you have:
  • Python 3.13 or later
  • uv package manager
  • Git (for cloning the repository)
  • For OCI servers: OCI CLI configured with appropriate credentials

​
Environment Setup

​
1. Create Virtual Environment

Set up a Python virtual environment with uv: 
uv venv --python 3.13 --seed
source .venv/bin/activate

​
2. Install Development Dependencies

Install the required development dependencies: 
uv pip install -r requirements-dev.txt

​
Building and Installing

​
Build All Servers

Build all MCP servers in the repository: 
make build
This command:
  • Iterates through all server directories in src/
  • Builds Python packages using uv build
  • Generates version metadata in __init__.py files

​
Install Servers Locally

Install the built servers into your virtual environment: 
make install
For development with locked dependencies: 
make sync
This installs all dependencies with exact versions from lock files, including development extras.

​
Build Specific Servers

To build only specific servers, use the SUBDIRS variable: 
SUBDIRS=src/oci-api-mcp-server make build
SUBDIRS=src/oci-api-mcp-server make install

​
MCP Client Configuration

Configure your MCP client to use the locally installed server packages instead of published versions.

​
Example Configuration

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "oracle.oci-api-mcp-server"
      ],
      "env": {
        "VIRTUAL_ENV": "/absolute/path/to/your/repo/.venv",
        "FASTMCP_LOG_LEVEL": "ERROR",
        "OCI_CONFIG_PROFILE": "DEFAULT"
      }
    }
  }
}
Replace /absolute/path/to/your/repo with the actual absolute path to your cloned repository, e.g., /Users/myuser/dev/oracle-mcp-servers

​
Testing

​
Run Linting

Check code quality with Ruff: 
make lint

​
Run Unit Tests

Execute the test suite with coverage reporting: 
make test
This command:
  • Runs pytest with coverage for each server
  • Generates HTML and terminal coverage reports
  • Combines coverage from all servers
  • Fails if coverage is below 69%

​
Code Formatting

Format code using Ruff: 
make format

​
MCP Inspector

Test your server interactively with MCP Inspector: 
npx @modelcontextprotocol/inspector \
  uv \
  --directory /absolute/path/to/server/code \
  run \
  server.py
Inspector opens a web interface (typically at http://127.0.0.1:6274) for debugging and testing your MCP server.

​
Dependency Management

​
Update Lock Files

Update uv.lock files for all servers: 
make lock

​
Verify Lock Files

Check that lock files are up to date: 
make lock-check

​
HTTP Transport Mode

To test servers in HTTP streaming mode locally: 
make build
make install
Then start the server with HTTP environment variables: 
VIRTUAL_ENV=$(pwd)/.venv ORACLE_MCP_HOST=127.0.0.1 ORACLE_MCP_PORT=8888 uv run oracle.oci-api-mcp-server
See the HTTP Mode guide for client configuration details.

​
Next Steps

Testing

Learn about testing strategies and tools

Contributing

Review contribution guidelines

Podman Deployment

Deploy servers in containers

HTTP Mode

Run servers with HTTP transport

Build docs developers (and LLMs) love

Get started for freeTalk to us