Инструмент Splunk MCP (протокол контекста модели)

Инструмент на основе FastMCP для взаимодействия с Splunk Enterprise/Cloud посредством естественного языка. Этот инструмент предоставляет набор возможностей для поиска данных Splunk, управления хранилищами KV и доступа к ресурсам Splunk через интуитивно понятный интерфейс.

Режимы работы

Инструмент работает в трех режимах:

Режим SSE (по умолчанию)
- Связь на основе событий, отправленных сервером
- Двунаправленное взаимодействие в реальном времени
- Подходит для веб-клиентов MCP
- Режим по умолчанию, когда аргументы не указаны
- Доступ через конечную точку /sse
Режим API
- Конечные точки RESTful API
- Доступ через префикс конечной точки /api/v1
- Начните с python splunk_mcp.py api
Режим STDIO
- Стандартная коммуникация на основе ввода/вывода
- Совместимость с Claude Desktop и другими клиентами MCP
- Идеально подходит для прямой интеграции с помощниками на основе искусственного интеллекта
- Начните с python splunk_mcp.py stdio

Related MCP server: Cloudflare MCP Server

Функции

Поиск Splunk : выполнение поиска Splunk с использованием запросов на естественном языке.
Управление индексами : список и проверка индексов Splunk
Управление пользователями : просмотр и управление пользователями Splunk.
Операции магазина KV : создание, перечисление и управление коллекциями магазина KV
Поддержка асинхронности : построено на основе шаблонов async/await для лучшей производительности
Подробное ведение журнала : комплексное ведение журнала с индикаторами эмодзи для лучшей видимости
Конфигурация SSL : гибкие возможности проверки SSL для различных требований безопасности.
Расширенная отладка : подробное протоколирование подключений и ошибок для устранения неполадок
Комплексное тестирование : модульные тесты, охватывающие все основные функции
Обработка ошибок : надежная обработка ошибок с соответствующими кодами состояния.
Соответствие SSE : Полностью соответствует спецификации MCP SSE

Доступные инструменты MCP

Через интерфейс MCP доступны следующие инструменты:

Управление инструментами

список_инструментов
- Перечисляет все доступные инструменты MCP с их описаниями и параметрами.

Проверка здоровья

проверка_здоровья
- Возвращает список доступных приложений Splunk для проверки подключения
пинг
- Простой пинг конечной точки для проверки работоспособности сервера MCP

Управление пользователями

текущий_пользователь
- Возвращает информацию о текущем аутентифицированном пользователе
список_пользователей
- Возвращает список всех пользователей и их ролей

Управление индексом

список_индексов
- Возвращает список всех доступных индексов Splunk.
получить_индексную_информацию
- Возвращает подробную информацию о конкретном индексе
- Параметры: index_name (строка)
индексы_и_типы_источников
- Возвращает полный список индексов и их исходных типов.

Поиск

поиск_splunk
- Выполняет поисковый запрос Splunk
- Параметры:
  - search_query (string): Строка поиска Splunk
  - early_time (строка, необязательно): Время начала окна поиска
  - latest_time (строка, необязательно): Время окончания окна поиска
  - max_results (целое число, необязательно): максимальное количество возвращаемых результатов
список_сохраненных_поисков
- Возвращает список сохраненных поисков в экземпляре Splunk.

Магазин КВ

список_kvstore_коллекции
- Список всех коллекций магазина KV
создать_kvstore_collection
- Создает новую коллекцию магазина KV
- Параметры: collection_name (строка)
удалить_kvstore_collection
- Удаляет существующую коллекцию магазина KV
- Параметры: collection_name (строка)

Конечные точки SSE

При работе в режиме SSE доступны следующие конечные точки:

/sse : Возвращает информацию о соединении SSE в формате текста/потока событий.
- Предоставляет метаданные о соединении SSE
- Включает URL для конечной точки сообщений
- Предоставляет информацию о протоколе и возможностях
/sse/messages : Основная конечная точка потока SSE
- Транслирует системные события, такие как сердцебиение
- Поддерживает постоянное соединение
- Отправляет правильно отформатированные события SSE
/sse/health : Конечная точка проверки работоспособности для режима SSE
- Возвращает информацию о статусе и версии в формате SSE

Обработка ошибок

Реализация MCP включает последовательную обработку ошибок:

Неверные команды поиска или неправильно сформированные запросы
Недостаточно прав
Ресурс не найден
Неверная проверка ввода
Неожиданные ошибки сервера
Проблемы с подключением к серверу Splunk

Все ответы об ошибках содержат подробное сообщение с объяснением ошибки.

Предпосылки

Python 3.10 или выше
Поэзия для управления зависимостью
Экземпляр Splunk Enterprise/Cloud
Соответствующие учетные данные Splunk с необходимыми разрешениями

Установка

Вариант 1: Локальная установка

Клонируйте репозиторий:

git clone <repository-url>
cd splunk-mcp

Установка зависимостей с помощью Poetry:

poetry install

Скопируйте пример файла среды и настройте параметры:

cp .env.example .env

Обновите файл .env , указав свои учетные данные Splunk:

SPLUNK_HOST=your_splunk_host
SPLUNK_PORT=8089
SPLUNK_USERNAME=your_username
SPLUNK_PASSWORD=your_password
SPLUNK_SCHEME=https
VERIFY_SSL=true
FASTMCP_LOG_LEVEL=INFO

Вариант 2: Установка Docker

Извлеките последнее изображение:

docker pull livehybrid/splunk-mcp:latest

Создайте файл .env , как указано выше, или используйте переменные среды напрямую.
Запустить с помощью Docker Compose:

docker-compose up -d

Или напрямую с помощью Docker:

docker run -i \
  --env-file .env \
  livehybrid/splunk-mcp

Использование

Местное использование

Инструмент может работать в трех режимах:

Режим SSE (по умолчанию для клиентов 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

Режим STDIO:

poetry run python splunk_mcp.py stdio

Использование Докера

Проект поддерживает как новые команды docker compose (V2), так и устаревшие команды docker-compose (V1). В примерах ниже используется синтаксис V2, но поддерживаются обе.

Режим SSE (по умолчанию):

docker compose up -d mcp

Режим API:

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

Режим STDIO:

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

Тестирование с помощью Docker

Проект включает в себя специальную тестовую среду в Docker:

Запустите все тесты:

./run_tests.sh --docker

Запустите определенные компоненты теста:

# 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

Результаты теста будут доступны в каталоге ./test-results .

Советы по разработке Docker

Изображения зданий :

# Build both images
docker compose build

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

Просмотр журналов :

# View all logs
docker compose logs

# Follow specific service logs
docker compose logs -f mcp

Отладка :

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

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

Примечание: Если вы используете Docker Compose V1, замените docker compose на docker-compose в приведенных выше командах.

Заметки о безопасности

Переменные среды :

Никогда не фиксируйте файлы .env
Использовать .env.example как шаблон
Рассмотрите возможность использования Docker-секретов для производства

Проверка SSL :

VERIFY_SSL=true рекомендуется для производства
Можно отключить для разработки/тестирования
Настройка через переменные среды

Портовая экспозиция :

Открывайте только необходимые порты
По возможности используйте внутреннюю сеть Docker
Рассмотрите возможность обеспечения сетевой безопасности в производстве

Переменные среды

Настройте следующие переменные среды:

SPLUNK_HOST : адрес вашего хоста Splunk
SPLUNK_PORT : порт управления Splunk (по умолчанию: 8089)
SPLUNK_USERNAME : Ваше имя пользователя Splunk
SPLUNK_PASSWORD : Ваш пароль Splunk
SPLUNK_SCHEME : Схема подключения (по умолчанию: https)
VERIFY_SSL : включить/отключить проверку SSL (по умолчанию: true)
FASTMCP_LOG_LEVEL : Уровень ведения журнала (по умолчанию: ИНФОРМАЦИЯ)
SERVER_MODE : режим сервера (sse, api, stdio) при использовании uvicorn

Конфигурация SSL

Инструмент предоставляет гибкие возможности проверки SSL:

Режим по умолчанию (безопасный) :

VERIFY_SSL=true

Полная проверка SSL-сертификата
Включена проверка имени хоста
Рекомендуется для производственных сред

Расслабленный режим :

VERIFY_SSL=false

Проверка SSL-сертификата отключена
Проверка имени хоста отключена
Полезно для тестирования или самоподписанных сертификатов.

Тестирование

Проект включает в себя комплексное тестирование с использованием pytest и сквозное тестирование с использованием специального клиента MCP:

Проведение тестов

Выполнение базового теста:

poetry run pytest

С отчетностью по охвату:

poetry run pytest --cov=splunk_mcp

С подробным выводом:

poetry run pytest -v

Сквозное тестирование SSE

Проект включает в себя специальный тестовый скрипт клиента MCP, который подключается к действующей конечной точке SSE и тестирует все инструменты:

# Test all tools
python test_endpoints.py

# Test specific tools
python test_endpoints.py health_check list_indexes

# List all available tools
python test_endpoints.py --list

Этот скрипт действует как клиент MCP:

Подключение к конечной точке /sse для получения URL-адреса сообщений
Отправка вызовов инструментов в конечную точку сообщений
Обработка событий SSE для извлечения результатов инструмента
Проверка результатов на соответствие ожидаемым форматам

Это обеспечивает реальное тестирование интерфейса SSE, как если бы он использовался реальным клиентом MCP.

Структура теста

В проекте используются три взаимодополняющих подхода к тестированию:

Интеграционные тесты MCP ( tests/test_api.py ) :
- Тестирует интерфейс инструментов MCP через mcp.call_tool()
- Проверяет правильную регистрацию инструмента с помощью FastMCP
- Обеспечивает правильный формат ответа и структуру данных
- Проверяет обработку ошибок на уровне интерфейса MCP
- Примечание: в идеале этот файл следует переименовать в test_mcp.py , чтобы лучше отразить его назначение.
Тесты прямой функции ( tests/test_endpoints_pytest.py ) :
- Тестирует функции Splunk напрямую (минуя уровень MCP)
- Обеспечивает более полное освещение деталей реализации функций.
- Тестирует пограничные случаи, вариации параметров и обработку ошибок
- Включает тесты конфигурации SSL, параметров соединения и тайм-аутов.
- Использует параметризованное тестирование для эффективного тестового покрытия
Сквозные тесты клиента MCP ( test_endpoints.py ) :
- Ведет себя как настоящий клиент MCP, подключающийся к конечной точке SSE
- Тестирует весь поток от подключения до вызова инструмента и анализа ответа.
- Проверяет фактическую реализацию протокола SSE
- Тестирует инструменты с реальными параметрами на реальном сервере
Тесты конфигурации ( tests/test_config.py ) :
- Тесты для анализа переменных окружения
- Настройки проверки SSL
- Проверка параметров соединения

Инструменты тестирования

Тесты подтверждают:

Асинхронное тестирование с помощью pytest-asyncio
Отчет о покрытии с помощью pytest-cov
Мошенничество с pytest-mock
Параметризованное тестирование
Тестирование тайм-аута соединения

Поиск неисправностей

Проблемы с подключением

Базовые возможности подключения :

Теперь инструмент выполняет базовую проверку TCP-подключения.
Проверьте, доступен ли порт 8089.
Проверьте сетевую маршрутизацию и брандмауэры

Проблемы с SSL :

Если вы видите ошибки SSL, попробуйте установить VERIFY_SSL=false
Проверьте действительность сертификата и цепочку доверия
Проверьте соответствие имени хоста сертификату

Проблемы аутентификации :

Проверьте учетные данные Splunk
Проверьте права пользователя
Убедитесь, что аккаунт не заблокирован

Отладка :

Установите FASTMCP_LOG_LEVEL=DEBUG для получения подробных журналов
Проверьте журналы подключений на наличие конкретных сообщений об ошибках.
Просмотр сообщений конфигурации SSL

Проблемы с подключением SSE :

Убедитесь, что конечная точка SSE доступна через /sse
Проверьте правильность заголовков типа контента
Используйте инструменты разработчика браузера для проверки соединений SSE

Клод Интеграция

Конфигурация рабочего стола Клода

Вы можете интегрировать Splunk MCP с Claude Desktop, настроив его на использование режима SSE или STDIO. Добавьте следующую конфигурацию в ваш claude_desktop_config.json :

Режим STDIO (рекомендуется для настольных компьютеров)

{
  "mcpServers": {
    "splunk": {
      "command": "poetry",
      "env": {
        "SPLUNK_HOST": "your_splunk_host",
        "SPLUNK_PORT": "8089",
        "SPLUNK_USERNAME": "your_username",
        "SPLUNK_PASSWORD": "your_password",
        "SPLUNK_SCHEME": "https",
        "VERIFY_SSL": "false"
      },
      "args": [
          "--directory",
          "/path/to/splunk-mcp",
          "run",
          "python",
          "splunk_mcp.py",
          "stdio"
      ]
    }
  }
}

Режим SSE

{
  "mcpServers": {
    "splunk": {
      "command": "poetry",
      "env": {
        "SPLUNK_HOST": "your_splunk_host",
        "SPLUNK_PORT": "8089",
        "SPLUNK_USERNAME": "your_username",
        "SPLUNK_PASSWORD": "your_password",
        "SPLUNK_SCHEME": "https",
        "VERIFY_SSL": "false",
        "FASTMCP_PORT": "8001",
        "DEBUG": "true"
      },
      "args": [
          "--directory",
          "/path/to/splunk-mcp",
          "run",
          "python",
          "splunk_mcp.py",
          "sse"
      ]
    }
  }
}

Использование с Клодом

После настройки вы сможете использовать естественный язык для взаимодействия со Splunk через Claude. Примеры:

Список доступных индексов:

What Splunk indexes are available?

Поиск данных Splunk:

Search Splunk for failed login attempts in the last 24 hours

Получите информацию о состоянии системы:

Check the health of the Splunk system

Управление магазинами KV:

List all KV store collections

Инструменты MCP будут автоматически доступны Клоду, что позволит ему выполнять эти операции с помощью команд на естественном языке.

Лицензия

[Ваша лицензия здесь]

Благодарности

Фреймворк FastMCP
Splunk SDK для Python
Python-decouple для управления конфигурацией
SSE Starlette для внедрения SSE