Splunk

Interaja com Splunk Enterprise/Cloud usando consultas em linguagem natural.

Documentação

⚠️ Este projeto está arquivado — use o Servidor MCP oficial da Splunk

Obrigado a todos que usaram, marcaram com estrela e fizeram fork deste projeto! 🙏 Ele começou como um esforço da comunidade para trazer suporte ao Protocolo de Contexto de Modelo (MCP) para a Splunk, muito antes de existir uma opção oficial.

A Splunk agora oferece um servidor MCP de primeira parte, totalmente suportado, que cresceu além do que este projeto da comunidade oferece. Por favor, migre para o servidor oficial:

📦 Servidor MCP da Splunk no Splunkbase (App 7931, da Splunk LLC): https://splunkbase.splunk.com/app/7931

📖 Documentação — Servidor MCP para a Plataforma Splunk: https://help.splunk.com/en/splunk-cloud-platform/mcp-server-for-splunk-platform/

Este repositório agora está somente leitura / arquivado e não receberá mais atualizações. O código abaixo é preservado para referência histórica. Obrigado novamente! 🚀

Splunk MCP (Protocolo de Contexto de Modelo) — Ferramenta

Uma ferramenta baseada em FastMCP para interagir com Splunk Enterprise/Cloud por meio de linguagem natural. Esta ferramenta fornece um conjunto de recursos para pesquisar dados do Splunk, gerenciar KV stores e acessar recursos do Splunk por meio de uma interface intuitiva.

Modos de operação

A ferramenta opera em três modos:

Modo SSE (padrão)
- Comunicação baseada em Server-Sent Events
- Interação bidirecional em tempo real
- Adequado para clientes MCP baseados na web
- Modo padrão quando nenhum argumento é fornecido
- Acesso via endpoint /sse
Modo API
- Endpoints RESTful
- Acesso via prefixo de endpoint /api/v1
- Iniciar com python splunk_mcp.py api
Modo STDIO
- Comunicação baseada em entrada/saída padrão
- Compatível com Claude Desktop e outros clientes MCP
- Ideal para integração direta com assistentes de IA
- Iniciar com python splunk_mcp.py stdio

Recursos

Pesquisa Splunk: Execute pesquisas no Splunk com consultas em linguagem natural
Gerenciamento de índices: Liste e inspecione índices do Splunk
Gerenciamento de usuários: Visualize e gerencie usuários do Splunk
Operações de KV Store: Crie, liste e gerencie coleções de KV store
Suporte assíncrono: Construído com padrões async/await para melhor desempenho
Logging detalhado: Logging abrangente com indicadores de emoji para melhor visibilidade
Configuração SSL: Opções flexíveis de verificação SSL para diferentes requisitos de segurança
Depuração aprimorada: Logging detalhado de conexão e erro para solução de problemas
Testes abrangentes: Testes de unidade cobrindo todas as funcionalidades principais
Tratamento de erros: Tratamento robusto de erros com códigos de status apropriados
Conformidade SSE: Totalmente compatível com a especificação MCP SSE

Ferramentas MCP disponíveis

As seguintes ferramentas estão disponíveis por meio da interface MCP:

Gerenciamento de ferramentas

list_tools
- Lista todas as ferramentas MCP disponíveis com suas descrições e parâmetros

Verificação de saúde

health_check
- Retorna uma lista de aplicativos Splunk disponíveis para verificar a conectividade
ping
- Endpoint simples de ping para verificar se o servidor MCP está ativo

Gerenciamento de usuários

current_user
- Retorna informações sobre o usuário autenticado no momento
list_users
- Retorna uma lista de todos os usuários e suas funções

Gerenciamento de índices

list_indexes
- Retorna uma lista de todos os índices Splunk acessíveis
get_index_info
- Retorna informações detalhadas sobre um índice específico
- Parâmetros: index_name (string)
indexes_and_sourcetypes
- Retorna uma lista abrangente de índices e seus sourcetypes

Pesquisa

search_splunk
- Executa uma consulta de pesquisa no Splunk
- Parâmetros:
  - search_query (string): string de pesquisa do Splunk
  - earliest_time (string, opcional): hora de início para a janela de pesquisa
  - latest_time (string, opcional): hora de término para a janela de pesquisa
  - max_results (inteiro, opcional): número máximo de resultados a retornar
list_saved_searches
- Retorna uma lista de pesquisas salvas na instância do Splunk

KV Store

list_kvstore_collections
- Lista todas as coleções de KV store
create_kvstore_collection
- Cria uma nova coleção de KV store
- Parâmetros: collection_name (string)
delete_kvstore_collection
- Exclui uma coleção de KV store existente
- Parâmetros: collection_name (string)

Endpoints SSE

Ao executar no modo SSE, os seguintes endpoints estão disponíveis:

/sse: Retorna informações de conexão SSE no formato text/event-stream
- Fornece metadados sobre a conexão SSE
- Inclui URL para o endpoint de mensagens
- Fornece informações de protocolo e capacidade
/sse/messages: O endpoint principal do fluxo SSE
- Transmite eventos do sistema, como heartbeats
- Mantém conexão persistente
- Envia eventos SSE formatados corretamente
/sse/health: Endpoint de verificação de saúde para o modo SSE
- Retorna informações de status e versão no formato SSE

Tratamento de erros

A implementação MCP inclui tratamento consistente de erros:

Comandos de pesquisa inválidos ou solicitações malformadas
Permissões insuficientes
Recurso não encontrado
Validação de entrada inválida
Erros inesperados do servidor
Problemas de conexão com o servidor Splunk

Todas as respostas de erro incluem uma mensagem detalhada explicando o erro.

Instalação

Usando UV (recomendado)

UV é um instalador e resolvedor de pacotes Python rápido, escrito em Rust. É significativamente mais rápido que pip e fornece melhor resolução de dependências.

Pré-requisitos

Python 3.10 ou superior
UV instalado (veja o guia de instalação do UV)

Início rápido com UV

Clone o repositório:

git clone <repository-url>
cd splunk-mcp

Instale as dependências com UV:

# Install main dependencies
uv sync

# Or install with development dependencies
uv sync --extra dev

Execute o aplicativo:

# SSE mode (default)
uv run python splunk_mcp.py

# STDIO mode
uv run python splunk_mcp.py stdio

# API mode
uv run python splunk_mcp.py api

Referência de comandos UV

# Install dependencies
uv sync

# Install with development dependencies
uv sync --extra dev

# Run the application
uv run python splunk_mcp.py

# Run tests
uv run pytest

# Run with specific Python version
uv run --python 3.11 python splunk_mcp.py

# Add a new dependency
uv add fastapi

# Add a development dependency
uv add --dev pytest

# Update dependencies
uv sync --upgrade

# Generate requirements.txt
uv pip compile pyproject.toml -o requirements.txt

Usando Poetry (alternativa)

Se você preferir Poetry, ainda pode usá-lo:

# Install dependencies
poetry install

# Run the application
poetry run python splunk_mcp.py

Usando pip (alternativa)

# Install dependencies
pip install -r requirements.txt

# Run the application
python splunk_mcp.py

Modos de operação

A ferramenta opera em três modos:

Modo SSE (padrão)
- Comunicação baseada em Server-Sent Events
- Interação bidirecional em tempo real
- Adequado para clientes MCP baseados na web
- Modo padrão quando nenhum argumento é fornecido
- Acesso via endpoint /sse
Modo API
- Endpoints RESTful
- Acesso via prefixo de endpoint /api/v1
- Iniciar com python splunk_mcp.py api
Modo STDIO
- Comunicação baseada em entrada/saída padrão
- Compatível com Claude Desktop e outros clientes MCP
- Ideal para integração direta com assistentes de IA
- Iniciar com python splunk_mcp.py stdio

Uso

Uso local

A ferramenta pode ser executada em três modos:

Modo SSE (padrão para clientes MCP):

# Start in SSE mode (default)
poetry run python splunk_mcp.py
# or explicitly:
poetry run python splunk_mcp.py sse

# Use uvicorn directly:
SERVER_MODE=api poetry run uvicorn splunk_mcp:app --host 0.0.0.0 --port 8000 --reload

Modo STDIO:

poetry run python splunk_mcp.py stdio

Uso com Docker

O projeto suporta os novos comandos docker compose (V2) e os legados docker-compose (V1). Os exemplos abaixo usam a sintaxe V2, mas ambos são suportados.

Modo SSE (padrão):

docker compose up -d mcp

Modo API:

docker compose run --rm mcp python splunk_mcp.py api

Modo STDIO:

docker compose run -i --rm mcp python splunk_mcp.py stdio

Testando com Docker

O projeto inclui um ambiente de teste dedicado no Docker:

Execute todos os testes:

./run_tests.sh --docker

Execute componentes de teste específicos:

# Run only the MCP server
docker compose up -d mcp

# Run only the test container
docker compose up test

# Run both with test results
docker compose up --abort-on-container-exit

Os resultados dos testes estarão disponíveis no diretório ./test-results.

Dicas de desenvolvimento com Docker

Construindo imagens:

# Build both images
docker compose build

# Build specific service
docker compose build mcp
docker compose build test

Visualizando logs:

# View all logs
docker compose logs

# Follow specific service logs
docker compose logs -f mcp

Depurando:

# Run with debug mode
DEBUG=true docker compose up mcp

# Access container shell
docker compose exec mcp /bin/bash

Nota: Se você estiver usando Docker Compose V1, substitua docker compose por docker-compose nos comandos acima.

Notas de segurança

Variáveis de ambiente:

Nunca envie arquivos .env para o controle de versão
Use .env.example como modelo
Considere usar segredos do Docker para produção

Verificação SSL:

VERIFY_SSL=true recomendado para produção
Pode ser desativado para desenvolvimento/testes
Configure por meio de variáveis de ambiente

Exposição de portas:

Exponha apenas as portas necessárias
Use rede interna do Docker quando possível
Considere a segurança da rede em produção

Variáveis de ambiente

Configure as seguintes variáveis de ambiente:

SPLUNK_HOST: Endereço do host Splunk
SPLUNK_PORT: Porta de gerenciamento do Splunk (padrão: 8089)
SPLUNK_USERNAME: Seu nome de usuário do Splunk
SPLUNK_PASSWORD: Sua senha do Splunk
SPLUNK_TOKEN: (Opcional) Token de autenticação do Splunk. Se definido, será usado em vez de nome de usuário/senha.
SPLUNK_SCHEME: Esquema de conexão (padrão: https)
VERIFY_SSL: Ativar/desativar verificação SSL (padrão: true)
FASTMCP_LOG_LEVEL: Nível de log (padrão: INFO)
SERVER_MODE: Modo do servidor (sse, api, stdio) ao usar uvicorn

Configuração SSL

A ferramenta fornece opções flexíveis de verificação SSL:

Modo padrão (seguro):

VERIFY_SSL=true

Verificação completa do certificado SSL
Verificação de nome de host ativada
Recomendado para ambientes de produção

Modo relaxado:

VERIFY_SSL=false

Verificação de certificado SSL desativada
Verificação de nome de host desativada
Útil para testes ou certificados autoassinados

Testes

O projeto inclui cobertura de testes abrangente usando pytest e testes de ponta a ponta com um cliente MCP personalizado:

Executando testes

Execução básica de testes:

poetry run pytest

Com relatório de cobertura:

poetry run pytest --cov=splunk_mcp