sharepoint-mcp

---

📑 Sumário

• Por que sharepoint-mcp?
• O que seu agente pode fazer
• Recursos
• Início rápido
• Docker
• Modos de transporte
• Integrações — Claude Desktop · VS Code Copilot · Cursor
• Todas as 14 ferramentas
• Referência de configuração
• Limitações
• Solução de problemas
• Desenvolvimento
• Documentação
• Contribuindo
• Segurança

---

🧠 Por que sharepoint-mcp?

A maioria dos agentes de IA só conhece o que está em seus dados de treinamento.
sharepoint-mcp dá ao seu agente acesso ao vivo ao conhecimento real da sua organização.

Sem sharepoint-mcp	Com sharepoint-mcp
🤷 O agente adivinha ou alucina	O agente lê o documento real
📋 Você copia e cola o conteúdo manualmente	O agente busca arquivos automaticamente
🔒 Conhecimento bloqueado no SharePoint	O conhecimento flui para o seu fluxo de trabalho de IA
🐌 Respostas estáticas e únicas	O agente raciocina, reescreve e salva de volta

---

🚀 O que seu agente pode fazer

📖 Entenda qualquer 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

✏️ Leia → Raciocine → Escreva

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

🗂️ Navegue pela sua biblioteca

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

📊 Formatos de arquivo suportados

📄 Formato	🤖 O que o agente recebe
PDF	Texto completo de cada página
Word .docx .doc	Conteúdo completo do documento
Excel .xlsx .xls	Todas as planilhas como texto estruturado
Texto, JSON, Markdown, HTML, YAML, Python	Conteúdo bruto como está
Imagens, ZIP, binários	Tipo de arquivo + Base64

---

✨ Recursos

	Recurso	Descrição
🔀	Suporte a API dupla	Escolha Office365 REST ou Microsoft Graph API
📁	Gerenciamento de pastas	Listar, criar, excluir, obter árvore recursiva completa
📄	Gerenciamento de documentos	Enviar, baixar, atualizar, excluir, pesquisar, ler conteúdo
🏷️	Gerenciamento de metadados	Ler e atualizar campos de itens de lista do SharePoint
🔍	Análise inteligente	Detecta automaticamente PDF / Word / Excel / texto
🔎	Pesquisa KQL	Pesquisa KQL nativa do SharePoint para encontrar arquivos semanticamente
📂	Escopo flexível de biblioteca	Escopo para uma subpasta ou acesso à raiz da biblioteca inteira
🔁	Repetição automática	Backoff exponencial em limitação 429/503 do SharePoint
🚀	Transporte duplo	stdio para desktop · http para Docker/remoto
🪵	Registro estruturado	JSON em produção · console colorido em desenvolvimento
🐳	Pronto para Docker	Comando único: docker compose up -d
🛡️	Contêiner não-root	Executa como usuário sem privilégios dentro do Docker
🩺	Verificação de saúde	Endpoint /health ao vivo com verificação real do SharePoint
🤖	CI/CD	Testado em Python 3.10 · 3.11 · 3.12 · 3.13

---

⚡ Início rápido

1️⃣ Instalar

pip install sharepoint-mcp

Ou a partir do código-fonte:

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

🔑 Novo no Azure AD? Siga o guia passo a passo →
🔀 Escolha sua API: o SharePoint MCP suporta tanto a API REST do Office365 (padrão) quanto a Microsoft Graph API. Consulte o Guia de configuração de API →

Opcional: Escopo para uma subpasta

Por padrão, o servidor acessa a raiz da biblioteca de documentos inteira. Para restringir operações a uma subpasta 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️⃣ Executar

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

# ▶️ Run directly
sharepoint-mcp

---

🐳 Docker

A maneira mais rápida de implantar para uso remoto ou em nuvem.

📋 Cenários de uso

Cenário A: Baixar a versão mais recente do DockerHub (recomendado)

Use isso para implantações em produção com a versão estável mais recente:

# 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

O que acontece: Baixa ravikant1918/sharepoint-mcp:latest do DockerHub com detecção automática de arquitetura (Intel/ARM).

---

Cenário B: Usar versão específica

Trave em uma versão específica para estabilidade ou testes:

# 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

O que acontece: Baixa ravikant1918/sharepoint-mcp:v1.0.1 em vez de latest.

---

Cenário C: Compilar localmente a partir do código-fonte

Use isso para desenvolvimento ou quando você fez alterações locais no 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

O que acontece: Compila a imagem a partir do Dockerfile local, marca como ravikant1918/sharepoint-mcp:latest e inicia o contêiner.

---

Cenário D: Usar imagem/fork personalizado

Se você fez fork do repositório e publicou no seu próprio 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

O que acontece: Baixa do seu registro/repositório personalizado.

---

🔧 Comandos comuns

# 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

Usando Podman? Basta substituir docker por podman — totalmente compatível.

Variáveis de ambiente do Docker

Variável	Padrão	Descrição
TRANSPORT	http	stdio ou http
HTTP_HOST	0.0.0.0	Endereço de vinculação
HTTP_PORT	8000	Porta
LOG_FORMAT	json	json ou console

---

🔌 Modos de transporte

Modo	Melhor para	Configurar com
stdio	Claude Desktop, Cursor, MCP Inspector	TRANSPORT=stdio (padrão)
http	Docker, agentes remotos, VS Code Copilot, clientes REST	TRANSPORT=http

---

🔗 Integrações

🤖 Claude Desktop

Adicione 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"
      }
    }
  }
}

💡 Omita SHP_DOC_LIBRARY para acessar a raiz da biblioteca inteira. Se sua organização usa a API REST do Office365 e renomeou a biblioteca padrão, defina também SHP_LIBRARY_NAME.

💻 VS Code Copilot (modo agente)

1. Inicie o servidor via Docker ou TRANSPORT=http sharepoint-mcp
2. Crie .vscode/mcp.json no seu espaço de trabalho:

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

3. Abra o Copilot Chat → mude para o modo agente → suas 14 ferramentas do SharePoint estão disponíveis.

⚠️ A barra final importa — a URL deve terminar com /mcp/ (não /mcp).

⌨️ Cursor / Continue

Adicione à sua configuração 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"
      }
    }
  }
}

---

🛠️ Todas as 14 ferramentas

📁 Gerenciamento de pastas

Ferramenta	O que faz
List_SharePoint_Folders	📋 Listar todas as subpastas em um diretório
Get_SharePoint_Tree	🌳 Obter árvore recursiva completa de pastas + arquivos
Create_Folder	➕ Criar uma nova pasta
Delete_Folder	🗑️ Excluir uma pasta vazia

📄 Gerenciamento de documentos

Ferramenta	O que faz
List_SharePoint_Documents	📋 Listar todos os arquivos com metadados
Search_SharePoint	🔎 Pesquisar documentos usando consultas KQL
Get_Document_Content	📖 Ler e analisar conteúdo de arquivo (PDF/Word/Excel/texto)
Upload_Document	⬆️ Enviar arquivo como string ou Base64
Upload_Document_From_Path	📂 Enviar um arquivo local diretamente
Update_Document	✏️ Sobrescrever conteúdo de arquivo existente
Delete_Document	🗑️ Excluir permanentemente um arquivo
Download_Document	⬇️ Baixar arquivo para o sistema de arquivos local

🏷️ Gerenciamento de metadados

Ferramenta	O que faz
Get_File_Metadata	🔍 Obter todos os campos de itens de lista do SharePoint
Update_File_Metadata	✏️ Atualizar campos de metadados

---

⚙️ Referência completa de configuração

Variável	Obrigatório	Padrão	Descrição
SHP_ID_APP	✅		ID do cliente do aplicativo Azure AD
SHP_ID_APP_SECRET	✅		Segredo do cliente Azure AD
SHP_TENANT_ID	✅		ID do locatário Microsoft
SHP_SITE_URL	✅		URL do site do SharePoint
SHP_API_TYPE		office365	office365, graph ou graphql
SHP_LIBRARY_NAME		Shared Documents	Nome da biblioteca (somente Office365 REST; Graph detecta automaticamente)
SHP_DOC_LIBRARY		(vazio = biblioteca inteira)	Escopo da subpasta (ex.: mcp_server). Vazio = biblioteca inteira
SHP_MAX_DEPTH		15	Profundidade máxima da árvore
SHP_MAX_FOLDERS_PER_LEVEL		100	Pastas por lote
SHP_LEVEL_DELAY		0.5	Atraso (s) entre níveis da árvore
TRANSPORT		stdio	stdio ou http
HTTP_HOST		0.0.0.0	Host de vinculação HTTP
HTTP_PORT		8000	Porta HTTP
LOG_LEVEL		INFO	DEBUG INFO WARNING ERROR
LOG_FORMAT		console	console ou json

---

⚠️ Limitações

Limitação	Detalhes
Site único	Conecta-se a um site do SharePoint por instância do servidor (multi-site planejado para v2.0)
Cliente síncrono	Usa chamadas síncronas à API REST do SharePoint (cliente assíncrono planejado para v1.3)
Sem compartilhamento	Ainda não é possível criar links de compartilhamento (planejado para v1.1)
Arquivos grandes	Arquivos muito grandes podem atingir limites de memória durante a extração de conteúdo
Limites de taxa	A limitação do SharePoint (429/503) é tratada com nova tentativa automática, mas operações em massa contínuas podem ser lentas

---

🔧 Solução de Problemas

Erros de Autenticação

Problema: Missing or invalid SharePoint credentials
Solução: Verifique se todas as 4 variáveis de ambiente obrigatórias estão definidas:

echo $SHP_ID_APP $SHP_ID_APP_SECRET $SHP_TENANT_ID $SHP_SITE_URL

Problemas de Conexão (Transporte HTTP)

Problema: O agente não consegue se conectar ao servidor MCP
Solução:

1. Certifique-se de que o servidor está em execução: curl http://localhost:8000/mcp/
2. Verifique se a URL termina com /mcp/ (a barra final é obrigatória)
3. Verifique se a porta não está bloqueada por um firewall

Contêiner Docker Não Saudável

Problema: podman ps / docker ps mostra (unhealthy)
Solução: Verifique os logs do contêiner para erros:

docker logs sharepoint-mcp

Registro de Depuração

Ative a saída detalhada definindo LOG_LEVEL=DEBUG:

LOG_LEVEL=DEBUG sharepoint-mcp

Para Docker, adicione ao seu arquivo .env ou docker-compose.yml:

LOG_LEVEL=DEBUG
LOG_FORMAT=console

Erros de Permissão

Problema: Access denied do SharePoint
Solução:

1. Verifique se o aplicativo do Azure AD possui as permissões de API necessárias
2. Garanta que o consentimento do administrador foi concedido (se exigido pela sua organização)
3. Confirme que SHP_SITE_URL aponta para um site ao qual seu aplicativo tem acesso

---

🧪 Desenvolvimento

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

---

📚 Documentação

📄 Doc	📝 Descrição
⚡ Primeiros Passos	Guia completo de configuração
⚙️ Configuração	Todas as variáveis de ambiente
🛠️ Referência de Ferramentas	Parâmetros detalhados das ferramentas
🏛️ Arquitetura	Diagrama de design e camadas
🔑 Configuração do Azure	Guia de registro do aplicativo Azure AD
🗺️ Roadmap	Recursos planejados
📅 Changelog	Histórico de versões

---

🤝 Contribuição

Contribuições são bem-vindas! Leia docs/contributing.md e nosso Código de Conduta.

1. 🍴 Faça um fork do repositório
2. 🌿 Crie um branch: git checkout -b feat/my-tool
3. ✅ Adicione testes: make test
4. 📬 Abra um Pull Request

---

🔒 Segurança

Encontrou uma vulnerabilidade? Por favor, não abra uma issue pública.
Reporte em particular via GitHub Security Advisories ou consulte SECURITY.md.

---