MCP Officegest

Servidor MCP que expõe a API Officegest v2 a clientes de IA como o Claude Code e o Claude Desktop.

A API tem 460 endpoints (inventário completo em endpoints-v2.txt); este servidor expõe um subconjunto curado de 22 tools com CRUD para três áreas: Clientes/Entidades, Vendas e Stocks.

Requisitos

• Python 3.12 (ver .python-version; o projeto usa pyenv + venv, não uv)
• Uma conta Officegest com acesso à API v2

Instalação

pyenv local 3.12.1
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuração

cp .env.example .env

Edita o .env:

OFFICEGEST_BASE_URL=https://A-TUA-EMPRESA.officegest.com/api/v2
OFFICEGEST_USERNAME=o-teu-utilizador
OFFICEGEST_PASSWORD=a-tua-password

⚠️ O .env contém credenciais e está no .gitignore — nunca o commites.

Autenticação

A API usa Bearer token no header Authorization. Com OFFICEGEST_USERNAME e OFFICEGEST_PASSWORD definidos, o servidor autentica-se sozinho na primeira chamada (POST /auth/login) e renova o token automaticamente se expirar (resposta 401). Em alternativa, podes colar um token já obtido em OFFICEGEST_TOKEN.

Nota: a API devolve o token em data.access_token (a documentação diz data.token, mas está desatualizada). O servidor aceita ambos.

Testar (MCP Inspector)

Este projeto usa pyenv + venv, por isso não uses mcp dev (arranca o servidor com uv, que não está instalado). Lança o Inspector apontando ao Python do venv:

npx @modelcontextprotocol/inspector .venv/bin/python server.py

Abre o link, faz Connect → Tools → List Tools e experimenta as tools.

Usar no Claude Code

A partir do projeto onde queres usar o MCP:

claude mcp add officegest -- /CAMINHO/ABSOLUTO/.venv/bin/python /CAMINHO/ABSOLUTO/server.py

O Claude Code passa a arrancar o servidor sozinho em cada sessão — não precisas de o correr à mão. Verifica com claude mcp list ou /mcp dentro da sessão.

Depois de alterares o server.py, rearranca o servidor (reabre o Claude Code ou /mcp → reconnect) para as mudanças serem lidas.

Tools disponíveis

Área	Tools
Clientes	listar_clientes, procurar_clientes, obter_cliente, obter_saldo_cliente, criar_cliente, atualizar_cliente
Vendas	listar_tipos_documento, listar_documentos_venda, obter_documento_venda, criar_documento_venda, atualizar_documento_venda, estado_documento_venda, atualizar_estado_documento, pagamentos_pendentes
Stocks	listar_artigos, criar_artigo, obter_artigo, atualizar_artigo, eliminar_artigo, consultar_stock, listar_familias, movimentos_stock

A API Officegest não tem delete para clientes nem documentos de venda (só artigos), por isso essas tools não existem — não é limitação deste servidor.

Adicionar mais endpoints

Cada tool é uma função async decorada com @mcp.tool(). Para expor outro endpoint, copia o padrão de uma tool existente e ajusta o caminho/parâmetros a partir de endpoints-v2.txt. A docstring é o que o modelo lê para decidir quando usar a tool — descreve bem os parâmetros.