sharepoint-mcp

---

📑 Índice de contenidos

• ¿Por qué sharepoint-mcp?
• Qué puede hacer tu agente
• Funciones
• Inicio rápido
• Docker
• Modos de transporte
• Integraciones — Claude Desktop · VS Code Copilot · Cursor
• Las 14 herramientas
• Referencia de configuración
• Limitaciones
• Solución de problemas
• Desarrollo
• Documentación
• Contribuciones
• Seguridad

---

🧠 ¿Por qué sharepoint-mcp?

La mayoría de los agentes de IA solo conocen lo que hay en sus datos de entrenamiento.
sharepoint-mcp le da a tu agente acceso en vivo al conocimiento real de tu organización.

Sin sharepoint-mcp	Con sharepoint-mcp
🤷 El agente adivina o alucina	El agente lee el documento real
📋 Copias y pegas contenido manualmente	El agente obtiene archivos automáticamente
🔒 Conocimiento bloqueado en SharePoint	El conocimiento fluye hacia tu flujo de IA
🐌 Respuestas estáticas y únicas	El agente razona, reescribe y guarda de vuelta

---

🚀 Qué puede hacer tu agente

📖 Entender cualquier documento

You: "Summarise the Q3 report in the Finance folder"
Agent: → Get_Document_Content("Finance", "Q3_Report.pdf")
       → Reads full extracted text
       → Returns a sharp, accurate summary

✏️ Leer → Razonar → Escribir

You: "Translate the proposal to French and save it"
Agent: → Get_Document_Content → translate → Upload_Document

🗂️ Navegar por tu biblioteca

You: "What files are in the Legal/Contracts folder?"
Agent: → List_SharePoint_Documents("Legal/Contracts")

📊 Formatos de archivo compatibles

📄 Formato	🤖 Lo que recibe el agente
PDF	Texto completo de cada página
Word .docx .doc	Contenido completo del documento
Excel .xlsx .xls	Todas las hojas como texto estructurado
Texto, JSON, Markdown, HTML, YAML, Python	Contenido sin procesar tal cual
Imágenes, ZIP, binarios	Tipo de archivo + Base64

---

✨ Funciones

	Función	Descripción
🔀	Soporte de API dual	Elige Office365 REST o Microsoft Graph API
📁	Gestión de carpetas	Listar, crear, eliminar, obtener árbol recursivo completo
📄	Gestión de documentos	Subir, descargar, actualizar, eliminar, buscar, leer contenido
🏷️	Gestión de metadatos	Leer y actualizar campos de elementos de lista de SharePoint
🔍	Análisis inteligente	Detecta automáticamente PDF / Word / Excel / texto
🔎	Búsqueda KQL	Búsqueda nativa de SharePoint KQL para encontrar archivos semánticamente
📂	Alcance de biblioteca flexible	Limita a una subcarpeta o accede a la raíz completa de la biblioteca
🔁	Reintento automático	Retroceso exponencial ante la limitación 429/503 de SharePoint
🚀	Transporte dual	stdio para escritorio · http para Docker/remoto
🪵	Registro estructurado	JSON en producción · consola con colores en desarrollo
🐳	Listo para Docker	Un solo comando: docker compose up -d
🛡️	Contenedor sin root	Se ejecuta como usuario sin privilegios dentro de Docker
🩺	Comprobación de salud	Endpoint /health en vivo con verificación real de SharePoint
🤖	CI/CD	Probado en Python 3.10 · 3.11 · 3.12 · 3.13

---

⚡ Inicio rápido

1️⃣ Instalar

pip install sharepoint-mcp

O desde el código fuente:

git clone https://github.com/ravikant1918/sharepoint-mcp.git
cd sharepoint-mcp && pip install -e .

2️⃣ Configurar

cp .env.example .env
# Open .env and fill in your Azure AD credentials

SHP_ID_APP=your-azure-app-client-id
SHP_ID_APP_SECRET=your-azure-app-secret
SHP_TENANT_ID=your-tenant-id
SHP_SITE_URL=https://your-tenant.sharepoint.com/sites/your-site
SHP_API_TYPE=office365   # or "graph" / "graphql" for Microsoft Graph API

🔑 ¿Nuevo en Azure AD? Sigue la guía paso a paso →
🔀 Elige tu API: SharePoint MCP es compatible con Office365 REST API (predeterminada) y Microsoft Graph API. Consulta la Guía de configuración de API →

Opcional: Limitar a una subcarpeta

De forma predeterminada, el servidor accede a la raíz completa de tu biblioteca de documentos. Para restringir las operaciones a una subcarpeta específica:

# Only operate within this subfolder (omit for full library access)
SHP_DOC_LIBRARY=mcp_server

# Library name (only needed if your org renamed "Shared Documents")
# Graph API auto-detects the default drive — this is only for Office365 REST API
# SHP_LIBRARY_NAME=Shared Documents

3️⃣ Ejecutar

# 🔍 Interactive testing with MCP Inspector
npx @modelcontextprotocol/inspector -- sharepoint-mcp

# ▶️ Run directly
sharepoint-mcp

---

🐳 Docker

La forma más rápida de implementar para uso remoto o en la nube.

📋 Escenarios de uso

Escenario A: Obtener la última versión de DockerHub (recomendado)

Úsalo para implementaciones de producción con la última versión estable:

# Step 1: Clone repository
git clone https://github.com/ravikant1918/sharepoint-mcp.git
cd sharepoint-mcp

# Step 2: Create .env file with your SharePoint credentials
cp .env.example .env
# Edit .env and fill in:
# SHP_ID_APP=your-app-id
# SHP_ID_APP_SECRET=your-secret
# SHP_TENANT_ID=your-tenant-id
# SHP_SITE_URL=https://yourcompany.sharepoint.com/sites/yoursite

# Step 3: Start container (pulls from DockerHub automatically)
docker compose up -d

# Step 4: Verify it's running
docker compose ps
curl http://localhost:8000/health

# View logs
docker compose logs -f

# Stop container
docker compose down

Qué ocurre: Obtiene ravikant1918/sharepoint-mcp:latest de DockerHub con detección automática de arquitectura (Intel/ARM).

---

Escenario B: Usar una versión específica

Fija una versión específica para mayor estabilidad o pruebas:

# Step 1: Set version via environment variable
SHAREPOINT_MCP_VERSION=v1.0.1 docker compose up -d

# Or add to .env file
echo "SHAREPOINT_MCP_VERSION=v1.0.1" >> .env
docker compose up -d

Qué ocurre: Obtiene ravikant1918/sharepoint-mcp:v1.0.1 en lugar de latest.

---

Escenario C: Compilar localmente desde el código fuente

Úsalo para desarrollo o cuando hayas realizado cambios locales en el código:

# Step 1: Clone and setup
git clone https://github.com/ravikant1918/sharepoint-mcp.git
cd sharepoint-mcp
cp .env.example .env
# Edit .env with your credentials

# Step 2: Build from local Dockerfile and start
docker compose up -d --build

# Step 3: Rebuild after code changes
docker compose down
docker compose up -d --build

Qué ocurre: Compila la imagen desde el Dockerfile local, la etiqueta como ravikant1918/sharepoint-mcp:latest e inicia el contenedor.

---

Escenario D: Usar una imagen/fork personalizado

Si has hecho fork del repositorio y lo has publicado en tu propio DockerHub:

# Use your custom image
SHAREPOINT_MCP_IMAGE=myusername/sharepoint-mcp \
SHAREPOINT_MCP_VERSION=dev \
docker compose up -d

# Or add to .env
echo "SHAREPOINT_MCP_IMAGE=myusername/sharepoint-mcp" >> .env
echo "SHAREPOINT_MCP_VERSION=dev" >> .env
docker compose up -d

Qué ocurre: Obtiene desde tu registro/repositorio personalizado.

---

🔧 Comandos comunes

# Start in detached mode
docker compose up -d

# Start with live logs
docker compose up

# View logs
docker compose logs -f

# Stop container
docker compose down

# Restart container
docker compose restart

# Pull latest image
docker compose pull

# Rebuild and restart
docker compose up -d --build

# Remove everything (including volumes)
docker compose down -v

¿Usas Podman? Solo reemplaza docker por podman — totalmente compatible.

Variables de entorno de Docker

Variable	Predeterminado	Descripción
TRANSPORT	http	stdio o http
HTTP_HOST	0.0.0.0	Dirección de enlace
HTTP_PORT	8000	Puerto
LOG_FORMAT	json	json o console

---

🔌 Modos de transporte

Modo	Mejor para	Se configura con
stdio	Claude Desktop, Cursor, MCP Inspector	TRANSPORT=stdio (predeterminado)
http	Docker, agentes remotos, VS Code Copilot, clientes REST	TRANSPORT=http

---

🔗 Integraciones

🤖 Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sharepoint": {
      "command": "sharepoint-mcp",
      "env": {
        "SHP_ID_APP": "your-app-id",
        "SHP_ID_APP_SECRET": "your-app-secret",
        "SHP_SITE_URL": "https://your-tenant.sharepoint.com/sites/your-site",
        "SHP_TENANT_ID": "your-tenant-id",
        "SHP_DOC_LIBRARY": "my-subfolder"
      }
    }
  }
}

💡 Omite SHP_DOC_LIBRARY para acceder a la raíz completa de la biblioteca. Si tu organización usa Office365 REST API y renombró la biblioteca predeterminada, también establece SHP_LIBRARY_NAME.

💻 VS Code Copilot (modo agente)

1. Inicia el servidor mediante Docker o TRANSPORT=http sharepoint-mcp
2. Crea .vscode/mcp.json en tu espacio de trabajo:

{
  "servers": {
    "sharepoint": {
      "url": "http://localhost:8000/mcp/",
      "type": "http"
    }
  }
}

3. Abre Copilot Chat → cambia al modo agente → tus 14 herramientas de SharePoint están disponibles.

⚠️ La barra final importa: la URL debe terminar con /mcp/ (no /mcp).

⌨️ Cursor / Continue

Añade a tu configuración de MCP (usa transporte stdio):

{
  "mcpServers": {
    "sharepoint": {
      "command": "sharepoint-mcp",
      "env": {
        "SHP_ID_APP": "your-app-id",
        "SHP_ID_APP_SECRET": "your-app-secret",
        "SHP_SITE_URL": "https://your-tenant.sharepoint.com/sites/your-site",
        "SHP_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

---

🛠️ Las 14 herramientas

📁 Gestión de carpetas

Herramienta	Qué hace
List_SharePoint_Folders	📋 Lista todas las subcarpetas de un directorio
Get_SharePoint_Tree	🌳 Obtiene el árbol completo recursivo de carpetas + archivos
Create_Folder	➕ Crea una carpeta nueva
Delete_Folder	🗑️ Elimina una carpeta vacía

📄 Gestión de documentos

Herramienta	Qué hace
List_SharePoint_Documents	📋 Lista todos los archivos con metadatos
Search_SharePoint	🔎 Busca documentos con consultas KQL
Get_Document_Content	📖 Lee y analiza el contenido del archivo (PDF/Word/Excel/texto)
Upload_Document	⬆️ Sube archivo como cadena o Base64
Upload_Document_From_Path	📂 Sube un archivo local directamente
Update_Document	✏️ Sobrescribe el contenido de un archivo existente
Delete_Document	🗑️ Elimina permanentemente un archivo
Download_Document	⬇️ Descarga archivo al sistema de archivos local

🏷️ Gestión de metadatos

Herramienta	Qué hace
Get_File_Metadata	🔍 Obtiene todos los campos de elementos de lista de SharePoint
Update_File_Metadata	✏️ Actualiza campos de metadatos

---

⚙️ Referencia completa de configuración

Variable	Obligatoria	Predeterminado	Descripción
SHP_ID_APP	✅		ID de cliente de la aplicación Azure AD
SHP_ID_APP_SECRET	✅		Secreto de cliente de Azure AD
SHP_TENANT_ID	✅		ID de inquilino de Microsoft
SHP_SITE_URL	✅		URL del sitio de SharePoint
SHP_API_TYPE		office365	office365, graph o graphql
SHP_LIBRARY_NAME		Shared Documents	Nombre de la biblioteca (solo Office365 REST; Graph lo detecta automáticamente)
SHP_DOC_LIBRARY		(vacío = biblioteca completa)	Alcance de subcarpeta (p. ej. mcp_server). Vacío = biblioteca completa
SHP_MAX_DEPTH		15	Profundidad máxima del árbol
SHP_MAX_FOLDERS_PER_LEVEL		100	Carpetas por lote
SHP_LEVEL_DELAY		0.5	Retraso (s) entre niveles del árbol
TRANSPORT		stdio	stdio o http
HTTP_HOST		0.0.0.0	Host de enlace HTTP
HTTP_PORT		8000	Puerto HTTP
LOG_LEVEL		INFO	DEBUG INFO WARNING ERROR
LOG_FORMAT		console	console o json

---

⚠️ Limitaciones

Limitación	Detalles
Sitio único	Se conecta a un sitio de SharePoint por instancia de servidor (multi-sitio planificado para v2.0)
Cliente síncrono	Utiliza llamadas síncronas a la API REST de SharePoint (cliente asíncrono planificado para v1.3)
Sin compartir	No puede crear enlaces de uso compartido todavía (planificado para v1.1)
Archivos grandes	Los archivos muy grandes pueden alcanzar los límites de memoria durante la extracción de contenido
Límites de velocidad	La limitación de SharePoint (429/503) se maneja con reintentos automáticos, pero las operaciones masivas sostenidas pueden ser lentas

---

🔧 Solución de problemas

Errores de autenticación

Problema: Missing or invalid SharePoint credentials
Solución: Verifique que las 4 variables de entorno requeridas estén configuradas:

echo $SHP_ID_APP $SHP_ID_APP_SECRET $SHP_TENANT_ID $SHP_SITE_URL

Problemas de conexión (Transporte HTTP)

Problema: El agente no puede conectarse al servidor MCP
Solución:

1. Asegúrese de que el servidor esté ejecutándose: curl http://localhost:8000/mcp/
2. Verifique que la URL termine con /mcp/ (se requiere la barra final)
3. Verifique que el puerto no esté bloqueado por un firewall

Contenedor Docker no saludable

Problema: podman ps / docker ps muestra (unhealthy)
Solución: Revise los registros del contenedor para ver errores:

docker logs sharepoint-mcp

Registro de depuración

Habilite la salida detallada configurando LOG_LEVEL=DEBUG:

LOG_LEVEL=DEBUG sharepoint-mcp

Para Docker, agregue a su archivo .env o docker-compose.yml:

LOG_LEVEL=DEBUG
LOG_FORMAT=console

Errores de permisos

Problema: Access denied de SharePoint
Solución:

1. Verifique que la aplicación de Azure AD tenga los permisos de API requeridos
2. Asegúrese de que se haya otorgado el consentimiento del administrador (si su organización lo requiere)
3. Confirme que SHP_SITE_URL apunte a un sitio al que su aplicación tenga acceso

---

🧪 Desarrollo

git clone https://github.com/ravikant1918/sharepoint-mcp.git
cd sharepoint-mcp
pip install -e ".[dev]"

make test      # run all tests
make inspect   # 🔍 launch MCP Inspector
make check     # quick import sanity check
make clean     # 🧹 remove caches

---

📚 Documentación

📄 Doc	📝 Descripción
⚡ Primeros pasos	Guía de configuración completa
⚙️ Configuración	Todas las variables de entorno
🛠️ Referencia de herramientas	Parámetros detallados de herramientas
🏛️ Arquitectura	Diagrama de diseño y capas
🔑 Configuración de Azure	Guía de registro de la aplicación de Azure AD
🗺️ Hoja de ruta	Funciones planificadas
📅 Registro de cambios	Historial de versiones

---

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lea docs/contributing.md y nuestro Código de conducta.

1. 🍴 Haga un fork del repositorio
2. 🌿 Cree una rama: git checkout -b feat/my-tool
3. ✅ Agregue pruebas: make test
4. 📬 Abra una solicitud de extracción (Pull Request)

---

🔒 Seguridad

¿Encontró una vulnerabilidad? Por favor, no abra un problema público.
Reporte de forma privada a través de Avisos de Seguridad de GitHub o consulte SECURITY.md.

---