MCP Oracle Cloud Infrastructure Server

Un servidor Model Context Protocol (MCP) para Oracle Cloud Infrastructure que permite listar y gestionar recursos tipo instancias.

Documentación

Este proyecto incluye varios documentos para ayudarte a configurar y utilizar el servidor MCP OCI:

• README.md - Este archivo, con información general
• INSTRUCTIONS.md - Guía paso a paso detallada para instalar y configurar
• CLAUDE-EXAMPLES.md - Ejemplos de cómo usar el servidor con Claude
• oci-keys-guide.md - Guía para generar claves API para OCI
• oci-config.example - Ejemplo de archivo de configuración OCI
• CHANGES.md - Registro de cambios importantes y solución de problemas

Requisitos previos

• Node.js v16 o superior
• npm v8 o superior
• Oracle Cloud Infrastructure CLI configurado
• Oracle Cloud Infrastructure SDK para Node.js
• Model Context Protocol SDK (@modelcontextprotocol/sdk)

Instalación

Existen varias formas de instalar este paquete:

Instalación rápida para Claude Desktop

Utiliza el script de instalación automatizado:

npm run install-claude

Este script instalará el paquete globalmente y configurará Claude Desktop automáticamente.

Instalación global

Puedes instalar este paquete globalmente:

npm install -g @jocebal/mcp-server-oci

O ejecutarlo directamente con npx:

npx -y @jocebal/mcp-server-oci

Configuración

Este servidor utiliza el archivo de configuración estándar de Oracle Cloud CLI, que normalmente se encuentra en ~/.oci/config. Asegúrate de que este archivo esté configurado correctamente antes de usar este servidor.

Ejemplo de un archivo de configuración OCI:

[DEFAULT]
user=ocid1.user.oc1..aaaaaaaa...
fingerprint=11:22:33:44:55:66:77:88:99:00:aa:bb:cc:dd:ee:ff
tenancy=ocid1.tenancy.oc1..aaaaaaaa...
region=us-ashburn-1
key_file=~/.oci/oci_api_key.pem

Uso

Iniciar el servidor

Para iniciar el servidor MCP con la configuración por defecto:

npx -y @jocebal/mcp-server-oci

Para especificar un perfil OCI diferente:

npx -y @jocebal/mcp-server-oci --profile MY_PROFILE

Para especificar un puerto diferente:

npx -y @jocebal/mcp-server-oci --port 3001

Integración con Claude Desktop

Para usar este servidor con Claude Desktop, añade la siguiente configuración a tu archivo claude_desktop_config.json:

{
  "tools": {
    "oracle-cloud": {
      "command": "/Users/jocebal/.nvm/versions/node/v22.15.0/bin/npx",
      "args": [
        "-y",
        "@jocebal/mcp-server-oci",
        "--profile",
        "DEFAULT"
      ],
      "env": {}
    }
  }
}

El archivo de configuración debe estar ubicado en:

• macOS: /Users/jocebal/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Herramientas disponibles

Este servidor MCP proporciona las siguientes herramientas:

1. list_compartments - Lista todos los compartimentos disponibles en tu cuenta de Oracle Cloud Infrastructure.
2. list_instances - Lista todas las instancias de cómputo en un compartimento específico.
3. get_instance - Obtiene información detallada sobre una instancia específica.
4. start_instance - Inicia una instancia detenida.
5. stop_instance - Detiene una instancia en ejecución.
6. restart_instance - Reinicia una instancia en ejecución.

Desarrollo

Estructura del proyecto

mcp-oci-server/
├── src/
│   ├── cli.ts             # Punto de entrada para la interfaz de línea de comandos
│   ├── oci/
│   │   └── client.ts      # Cliente OCI para interactuar con la API de Oracle Cloud
│   ├── server/
│   │   └── server.ts      # Implementación del servidor MCP
│   └── tools/
│       └── oci-tools.ts   # Definición de herramientas MCP para OCI
├── package.json
├── tsconfig.json
└── README.md

Compilación

Existen varias formas de compilar el proyecto:

Compilación y empaquetado automatizado

Utiliza el script de compilación automatizado:

npm run build-package

Este script limpiará, compilará y empaquetará el proyecto, y te preguntará si quieres publicarlo en npm.

Compilación manual

npm install
npm run build

Ejecutar en modo desarrollo

npm run dev

Solución de problemas

Si encuentras errores durante la instalación o compilación, consulta el archivo CHANGES.md que contiene información detallada sobre los cambios realizados y cómo resolver problemas comunes.

Error de autenticación

Si recibes errores de autenticación, verifica que:

1. El archivo ~/.oci/config existe y contiene las credenciales correctas
2. El archivo de clave privada referenciado en el config existe y tiene los permisos correctos
3. Las credenciales en el archivo de configuración son válidas

Error de conexión

Si el servidor no puede conectarse a OCI, verifica que:

1. Tu conexión a internet funciona correctamente
2. La región configurada en tu archivo de configuración OCI es correcta
3. No hay firewalls o proxies bloqueando la conexión

Licencia

MIT