Skip to main content
Glama

🏛️ SEI MCP Server (Python) — Model Context Protocol for SEI WebServices v3.1+

An enterprise-grade Model Context Protocol (MCP) server built in Python that exposes the official SEI (Sistema Eletrônico de Informações) SOAP Web Services (SEI-WebServices-v3.1.pdf / sei.wsdl), SIP (Sistema de Permissões) Web Services, and External RH Web Services as 72 structured MCP tools for Google Cloud Gemini Enterprise, Claude Desktop, Cursor, and MCP Inspector.


✨ Key Features

  • Complete SEI v3.1+ Coverage (72 MCP Tools):

    • 25 Process & Workflow (Procedimentos) Tools: gerarProcedimento, consultarProcedimento, consultarProcedimentoIndividual, enviarProcesso, concluirProcesso, reabrirProcesso, sobrestarProcesso, removerSobrestamentoProcesso, anexarProcesso, desanexarProcesso, relacionarProcesso, removerRelacionamentoProcesso, atribuirProcesso, lancarAndamento, listarAndamentos, registrarAnotacao, bloquearProcesso, desbloquearProcesso, adicionarMarcador, removerMarcador, listarAndamentosMarcadores, definirControlePrazo, concluirControlePrazo, removerControlePrazo, listarExtensoesPermitidas.

    • 13 Document & File (Documentos & Arquivos) Tools: incluirDocumento, consultarDocumento, cancelarDocumento, gerarBloco, adicionarArquivo, adicionarConteudoArquivo, listarHipotesesLegais, listarTiposConferencia, agendarPublicacao, alterarPublicacao, cancelarAgendamentoPublicacao, consultarPublicacao, enviarEmail.

    • 12 Signature, Meeting & Internal Block (Blocos) Tools: incluirDocumentoBloco, retirarDocumentoBloco, incluirProcessoBloco, retirarProcessoBloco, disponibilizarBloco, cancelarDisponibilizacaoBloco, excluirBloco, reabrirBloco, devolverBloco, consultarBloco, listarBlocos, concluirBloco.

    • 17 Catalog & Parameter (Parâmetros) Tools: listarUnidades, listarTiposProcedimento, listarSeries, listarContatos, atualizarContatos, listarUsuarios, listarPaises, listarEstados, listarCidades, listarCargos, listarFeriados, listarMarcadoresUnidade, definirMarcador, listarTiposPrioridade, confirmarDisponibilizacaoPublicacao, enviarNotificacaoPublicacao, SinalizarDocumento.

    • 3 SIP Permission (SIP) Tools: sip_listarPermissao, sip_replicarPermissao, sip_replicarUsuario.

    • 1 External HR (RH) Tool: rh_listarCargoFuncao.

    • 1 Diagnostic Tool: get_system_info.

  • Dual-Transport HTTP Server (StreamableHTTP & SSE) + stdio:

    • POST /mcp: Modern MCP StreamableHTTP transport (used by Google Cloud Gemini Enterprise).

    • GET /sse & POST /messages?sessionId=...: Legacy MCP Server-Sent Events (SSE) transport.

    • --stdio: Standard input/output transport for local CLI / IDE agents.

  • Gemini Enterprise OAuth 2.0 Authentication & Discovery:

    • Exposes RFC 9728 GET /.well-known/oauth-protected-resource and RFC 8414 GET /.well-known/oauth-authorization-server.

    • Allows unauthenticated MCP discovery handshakes (initialize, notifications/initialized, ping, tools/list) so Gemini Enterprise's "Validate & Save" and "Reload custom actions" always succeed.

    • Enforces Google OAuth 2.0 Bearer token validation (via https://oauth2.googleapis.com/tokeninfo) and optional OAUTH_CLIENT_ID audience verification on all tools/call tool executions in production.

  • Official SEI SOAP 1.1 RPC/Encoded Integration:

    • Parses sei-documentation/sei.wsdl to serialize all <wsdl:part> parameters in exact positional order as required by PHP's SoapServer (controlador_ws.php?servico=sei).

    • Handles SOAP-ENC:Array (<item> elements), xsi:nil="true" optional fields, Base64 encoding, and MD5 checksum helpers for incluirDocumento and adicionarArquivo.


Related MCP server: mcp-brasil

🏗️ System Architecture

flowchart LR
    subgraph Clients["MCP Clients"]
        GE["Google Cloud\nGemini Enterprise"]
        IDE["Claude / Cursor /\nMCP Inspector"]
    end

    subgraph GCP["Google Cloud Platform (infra/ Terraform)"]
        ALB["Global External HTTPS\nLoad Balancer + Static IP"]
        NEG["Serverless NEG"]
        CR["Cloud Run Service\n(sei-mcp-server Python)"]
    end

    subgraph GovEnv["SEI / SIP Environment"]
        SEI["SEI SOAP WebService\n/sei/controlador_ws.php?servico=sei"]
        SIP["SIP SOAP WebService\n/sip/controlador_ws.php?servico=wsdl"]
    end

    GE -- "StreamableHTTP (POST /mcp)\n+ OAuth 2.0 Bearer Token" --> ALB
    IDE -- "SSE (/sse) or StreamableHTTP" --> ALB
    ALB --> NEG --> CR
    CR -- "SOAP 1.1 RPC/Encoded\n(SiglaSistema + IdentificacaoServico)" --> SEI
    CR -- "SOAP 1.1 RPC/Encoded" --> SIP

🔐 Authentication Architecture

This server implements two distinct authentication layers:

1. Inbound Authentication: Gemini Enterprise -> MCP Server (OAuth 2.0)

Following the Gemini Enterprise MCP specification (mirrored from sei-mcp-prodesp):

Endpoint / Method

Auth Requirement

Purpose

GET /health

Public

Liveness & readiness probe

GET /.well-known/oauth-protected-resource

Public

RFC 9728 OAuth 2.0 Protected Resource Metadata

GET /.well-known/oauth-authorization-server

Public

RFC 8414 OAuth 2.0 Authorization Server Metadata

POST /mcp (initialize, notifications/initialized, ping, tools/list)

Public

Allows Gemini Enterprise to discover tools during connector registration

POST /mcp (tools/call)

OAuth 2.0 Bearer Token

Validates Google OAuth 2.0 access token & OAUTH_CLIENT_ID audience

  • In Production (ENV=production and OAUTH_ENABLED=true): Every tools/call invocation must carry Authorization: Bearer <google_access_token>.

  • In Local Development (ENV=development and OAUTH_ENABLED=false): tools/call can be invoked without an OAuth token for rapid testing.

2. Outbound Authentication: MCP Server -> SEI Web Services (SEI-WebServices-v3.1.pdf)

Per the official SEI WebServices v3.1 Manual (sei-documentation/SEI-WebServices-v3.1.pdf, pages 5–8), every SOAP operation authenticates using:

  1. SiglaSistema (SEI_SIGLA_SISTEMA): System acronym registered in SEI under Administração -> Sistemas -> Novo.

  2. IdentificacaoServico (SEI_IDENTIFICACAO_SERVICO): Either:

    • The 72-character Access Key (Chave de Acesso) generated in SEI (Administração -> Sistemas -> Serviços -> Chave de Acesso) — recommended by SEI v3.1+, OR

    • The plain-text service name (Identificação) prefixed by its SHA-256 hash when authenticating against legacy SEI 3.0 services.

  3. IP Whitelisting (Servidores): In SEI under Administração -> Sistemas -> listar -> Serviços -> Servidores, register the outbound IP address (or CIDR mask) of the MCP server so SEI permits SOAP calls for the configured operations (Operações).

  4. IdUnidade (SEI_ID_UNIDADE): Default organizational unit ID automatically injected when not explicitly passed by the user in a tool call.


🧰 Complete Catalog of 72 MCP Tools

🩺 System & Diagnostics (1 Tool)

Tool Name

Description

get_system_info

Returns server status, configured SEI/SIP endpoints, default unit ID, and registered tool count.

📁 Process & Workflow Tools — src/tools/processos.py (25 Tools)

Tool Name

SEI WSDL Operation

Description

gerarProcedimento

gerarProcedimento

Creates a new administrative process (Procedimento) with optional initial documents, subjects, interested parties, and destination units.

consultarProcedimento

consultarProcedimento

Queries comprehensive metadata of a process (subjects, interested parties, units, open locations, related/annexed processes).

consultarProcedimentoIndividual

consultarProcedimentoIndividual

Queries individual process metadata in a specific context.

enviarProcesso

enviarProcesso

Forwards (tramita) a process to one or more destination units (UnidadesDestino).

concluirProcesso

concluirProcesso

Concludes (fecha) a process in the specified unit.

reabrirProcesso

reabrirProcesso

Reopens a previously concluded process in the specified unit.

sobrestarProcesso

sobrestarProcesso

Suspends (sobresta) a process, optionally linking it to another process.

removerSobrestamentoProcesso

removerSobrestamentoProcesso

Removes the suspension (sobrestamento) from a process.

anexarProcesso

anexarProcesso

Annexes a subsidiary process (ProtocoloProcedimentoAnexado) to a principal process.

desanexarProcesso

desanexarProcesso

Detaches (desanexa) an annexed process from its principal process.

relacionarProcesso

relacionarProcesso

Creates a bidirectional link (relacionamento) between two processes.

removerRelacionamentoProcesso

removerRelacionamentoProcesso

Removes a relationship link between two processes.

atribuirProcesso

atribuirProcesso

Assigns (atribui) a process to a specific user (IdUsuario) within the unit.

lancarAndamento

lancarAndamento

Records a workflow progress entry (andamento) in the process history.

listarAndamentos

listarAndamentos

Lists workflow history entries (andamentos) for a process.

registrarAnotacao

registrarAnotacao

Registers or updates a unit note (anotação) on one or more processes.

bloquearProcesso

bloquearProcesso

Locks (bloqueia) a process to prevent modifications.

desbloquearProcesso

desbloquearProcesso

Unlocks (desbloqueia) a previously locked process.

adicionarMarcador

adicionarMarcador

Applies unit markers/tags (marcadores) to one or more processes.

removerMarcador

removerMarcador

Removes unit markers/tags (marcadores) from one or more processes.

listarAndamentosMarcadores

listarAndamentosMarcadores

Lists the history of marker changes on a process in the unit.

definirControlePrazo

definirControlePrazo

Sets a deadline (controle de prazo by date or days) on one or more processes.

concluirControlePrazo

concluirControlePrazo

Marks a deadline control as completed on one or more processes.

removerControlePrazo

removerControlePrazo

Removes a deadline control from one or more processes.

listarExtensoesPermitidas

listarExtensoesPermitidas

Lists file extensions permitted for external document uploads in SEI.

📄 Document & File Tools — src/tools/documentos.py (13 Tools)

Tool Name

SEI WSDL Operation

Description

incluirDocumento

incluirDocumento

Includes a generated (G) or external (R) document in a process (supports automatic Base64 encoding via ConteudoTextoPlano).

consultarDocumento

consultarDocumento

Queries document metadata, signatures, publication data, and view link (LinkAcesso).

cancelarDocumento

cancelarDocumento

Cancels a document with justification (Motivo).

gerarBloco

gerarBloco

Creates a new Signature (A), Internal (I), or Meeting (R) block.

adicionarArquivo

adicionarArquivo

Starts a chunked file upload (IdArquivo) with automatic Base64 & MD5 calculation if ConteudoTextoPlano is supplied.

adicionarConteudoArquivo

adicionarConteudoArquivo

Appends a Base64 content chunk to an in-progress IdArquivo upload.

listarHipotesesLegais

listarHipotesesLegais

Lists legal hypotheses (Hipóteses Legais) for restricted (Restrito) or confidential (Sigiloso) access levels.

listarTiposConferencia

listarTiposConferencia

Lists authentication/certification types (Tipos de Conferência) for external documents.

agendarPublicacao

agendarPublicacao

Schedules a document for official publication (Publicação).

alterarPublicacao

alterarPublicacao

Modifies an existing publication schedule.

cancelarAgendamentoPublicacao

cancelarAgendamentoPublicacao

Cancels a scheduled document publication.

consultarPublicacao

consultarPublicacao

Queries publication details by publication ID, document ID, or protocol.

enviarEmail

enviarEmail

Sends an official email from within a process (Procedimento), recording the email as a process document.

📦 Block, Catalog, SIP & RH Tools — src/tools/parametros.py (33 Tools)

Tool Name

Service / WSDL Operation

Description

incluirDocumentoBloco

SEI: incluirDocumentoBloco

Adds a document to a signature (A) or internal/meeting block (IdBloco).

retirarDocumentoBloco

SEI: retirarDocumentoBloco

Removes a document from a block.

incluirProcessoBloco

SEI: incluirProcessoBloco

Adds a process (ProtocoloProcedimento) to an internal or meeting block.

retirarProcessoBloco

SEI: retirarProcessoBloco

Removes a process from a block.

disponibilizarBloco

SEI: disponibilizarBloco

Makes a block available (disponibiliza) to its destination units.

cancelarDisponibilizacaoBloco

SEI: cancelarDisponibilizacaoBloco

Cancels the availability of a block.

excluirBloco

SEI: excluirBloco

Deletes one or more blocks (IdBlocos).

reabrirBloco

SEI: reabrirBloco

Reopens a concluded block.

devolverBloco

SEI: devolverBloco

Returns (devolve) a block received from another unit.

consultarBloco

SEI: consultarBloco

Queries details of a block and optionally lists its protocols (SinRetornarProtocolos).

listarBlocos

SEI: listarBlocos

Lists blocks filtered by type (A, R, I), state (G, D, R, C), and unit.

concluirBloco

SEI: concluirBloco

Concludes one or more blocks.

listarUnidades

SEI: listarUnidades

Lists organizational units (Unidades) permitted for the service.

listarTiposProcedimento

SEI: listarTiposProcedimento

Lists process types (Tipos de Processo).

listarSeries

SEI: listarSeries

Lists document types (Séries).

listarContatos

SEI: listarContatos

Searches contacts (Contatos) by type, words, CPF/CNPJ, or IDs.

atualizarContatos

SEI: atualizarContatos

Creates (I), alters (A), or deactivates (E) contact records in batch.

listarUsuarios

SEI: listarUsuarios

Lists users with permission in the unit.

listarPaises

SEI: listarPaises

Lists countries (Países) registered in SEI.

listarEstados

SEI: listarEstados

Lists states/provinces (UF) registered in SEI.

listarCidades

SEI: listarCidades

Lists cities (Municípios + IBGE code) registered in SEI.

listarCargos

SEI: listarCargos

Lists official titles/positions (Cargos).

listarFeriados

SEI: listarFeriados

Lists holidays (Feriados) for an organ within a date range.

listarMarcadoresUnidade

SEI: listarMarcadoresUnidade

Lists markers (Marcadores) available in the unit.

definirMarcador

SEI: definirMarcador

Creates or updates unit marker definitions (DefinicaoMarcador).

listarTiposPrioridade

SEI: listarTiposPrioridade

Lists priority types (Tipos de Prioridade).

confirmarDisponibilizacaoPublicacao

SEI: confirmarDisponibilizacaoPublicacao

Confirms publication availability in an external publication vehicle.

enviarNotificacaoPublicacao

SEI: enviarNotificacaoPublicacao

Sends a publication notification in SEI.

SinalizarDocumento

SEI: SinalizarDocumento

Applies visual flags/signals (Sinalizações) to documents.

sip_listarPermissao

SIP: listarPermissao

Queries permissions registered in SIP (Sistema de Permissões).

sip_replicarPermissao

SIP: replicarPermissao

Replicates permissions in SIP across users/units.

sip_replicarUsuario

SIP: replicarUsuario

Replicates/synchronizes user records in SIP (I include, A alter, D deactivate, R reactivate, C query).

rh_listarCargoFuncao

RH: listarCargoFuncao

Queries job titles/functions (Cargo/Função) from an external HR SOAP Web Service.


🚀 Quickstart (Local Development)

1. Clone & Configure Environment

cp .env.example .env

Edit .env with your SEI credentials:

PORT=3000
HOST=0.0.0.0
ENV=development
OAUTH_ENABLED=false

# SEI SOAP WebService Configuration
SEI_WS_URL=https://sei.orgao.gov.br/sei/controlador_ws.php?servico=sei
SEI_SIGLA_SISTEMA=MCP_GEMINI
SEI_IDENTIFICACAO_SERVICO=<72-character-chave-de-acesso>
SEI_ID_UNIDADE=110000958
SEI_VERIFY_SSL=true
SEI_TIMEOUT_SECONDS=60

# Optional SIP & RH WebService URLs
SIP_WS_URL=https://sei.orgao.gov.br/sip/controlador_ws.php?servico=wsdl
RH_WS_URL=

2. Install Dependencies (Optional if system packages are present)

pip install -r requirements.txt

3. Run the Server

# Start Dual-Transport HTTP Server (StreamableHTTP /mcp + SSE /sse)
python3 -m src.server

# Or run over stdio transport for local CLI clients
python3 -m src.server --stdio

4. Run Unit & cURL Integration Tests

# Run Python unit test suite (WSDL parser, SOAP serializer, MCP JSON-RPC, OAuth 2.0)
python3 -m unittest discover -s tests -v

# Run automated 13-test cURL suite against a running server
./scripts/test-mcp-curl.sh --url http://localhost:3000

☁️ Deploying to Google Cloud Run with Terraform

Step 1: Build and Push Container Image via Cloud Build

gcloud builds submit --config=cloudbuild.yaml --project=YOUR_GCP_PROJECT_ID

Step 2: Provision Cloud Run + Global HTTPS Load Balancer with Terraform

The infra/ directory provisions:

  • Google Cloud APIs (run.googleapis.com, compute.googleapis.com)

  • Cloud Run v2 Service running sei-mcp-server

  • Global Static IP Address + Google-Managed SSL Certificate

  • Global External Application Load Balancer + Serverless NEG

cd infra
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your project_id, domain, and SEI credentials
terraform init
terraform plan
terraform apply

See infra/README.md for detailed DNS and SSL certificate provisioning instructions.


🤖 Connecting to Google Cloud Gemini Enterprise

  1. Open the Google Cloud Console -> Gemini Enterprise -> Extensions / Custom Actions (MCP).

  2. Click Add MCP Server and configure:

    • Server URL: https://<YOUR_LOAD_BALANCER_DOMAIN>/mcp

    • Transport: Streamable HTTP

    • Authentication: OAuth 2.0

      • Client ID: Matches OAUTH_CLIENT_ID configured on Cloud Run

      • Client Secret: Your Google OAuth 2.0 Client Secret

      • Authorization URL: https://accounts.google.com/o/oauth2/v2/auth

      • Token URL: https://oauth2.googleapis.com/token

      • Scopes: openid email profile

  3. Click Validate & Save. Gemini Enterprise will perform an unauthenticated initialize and tools/list handshake to discover all 72 SEI tools, and will attach the end-user's OAuth 2.0 Bearer token on every tools/call execution.


📂 Project Structure

sei-mcp/
├── src/
│   ├── __init__.py
│   ├── config.py              # Environment & SEI/OAuth configuration loader
│   ├── auth.py                # Google OAuth 2.0 token verifier & MCP discovery bypass
│   ├── mcp_server.py          # JSON-RPC 2.0 MCP router (initialize, tools/list, tools/call)
│   ├── server.py              # Dual-transport HTTP server (/mcp, /sse, /messages, /health)
│   ├── client/
│   │   ├── __init__.py
│   │   └── sei_client.py      # WSDL parser & SOAP 1.1 RPC/Encoded client for SEI/SIP/RH
│   └── tools/
│       ├── __init__.py        # Registers all 72 MCP tools
│       ├── processos.py       # 25 Process & workflow tools
│       ├── documentos.py      # 13 Document, file upload, publication & email tools
│       └── parametros.py      # 12 Block tools + 17 Catalog tools + 3 SIP + 1 RH tool
├── tests/
│   ├── test_wsdl_and_soap.py  # Unit tests for WSDL parsing & SOAP 1.1 serialization
│   └── test_mcp_server.py     # Unit tests for MCP JSON-RPC & OAuth 2.0 middleware
├── scripts/
│   └── test-mcp-curl.sh       # Automated 13-test cURL test suite (/health, /mcp, /sse)
├── infra/                     # Terraform IaC (Cloud Run v2 + Global HTTPS Load Balancer)
├── sei-documentation/         # Official SEI WebServices v3.1 PDF manual & sei.wsdl
├── Dockerfile                 # Production Python 3.12 Slim container image
├── cloudbuild.yaml            # Google Cloud Build pipeline
├── pyproject.toml             # Python packaging & pytest/ruff/mypy configuration
└── requirements.txt           # Pinned Python dependencies

📄 License

Licensed under the MIT License.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Bridges AI agents to the Brazilian SEI system, enabling listing processes, reading documents, searching, and downloading files via session cookies.
      2
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      MCP Server for accessing 36 Brazilian public data sources and 1 agent, enabling AI agents to query government data on economy, legislation, transparency, judiciary, elections, environment, health, and more.
      6
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      MCP Server do SEI Pro para o SEI (Sistema Eletrônico de Informações) via API REST mod-wssei v2 + scraper do frontend web (modo híbrido).
      100
      21
      MIT