servicenow-mcp

Небольшой MCP сервер, который позволяет ИИ-агентам создавать, искать и обновлять инциденты ServiceNow через Table API. Построен с использованием официального Python пакета mcp (декораторы в стиле FastMCP), httpx и python-dotenv. Работает через stdio.

Всё находится в одном файле: server.py.

Настройка

Требуется Python 3.12+ и uv.

uv sync

Создайте .env рядом с server.py (он игнорируется git) с учётными данными для базовой аутентификации для вашего экземпляра — подойдёт Personal Developer Instance:

SNOW_INSTANCE_URL=https://devXXXXXX.service-now.com
SNOW_USERNAME=admin
SNOW_PASSWORD=your-password
# optional, default 15
SNOW_TIMEOUT_SECONDS=15

Запустите сервер (он общается по MCP через stdin/stdout, поэтому ничего не видно — MCP клиент должен его запускать):

uv run server.py

Регистрация в MCP клиенте

Укажите клиенту на uv с директорией проекта, чтобы .venv и .env были найдены:

{
  "mcpServers": {
    "servicenow": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/servicenow-mcp", "run", "server.py"]
    }
  }
}

Для Claude Code: claude mcp add servicenow -- uv --directory /absolute/path/to/servicenow-mcp run server.py.

Переменные окружения, уже установленные в окружении клиента, имеют приоритет над .env.

Related MCP server: sn-mcp-bridge

Инструменты

Все инструменты возвращают читаемую ошибку инструмента (отображается агенту как isError) вместо трассировки стека, например:

• Authentication failed (401): check SNOW_USERNAME and SNOW_PASSWORD. ServiceNow said: User is not authenticated …

• Could not connect to https://…: [Errno 8] nodename nor servname provided … Check SNOW_INSTANCE_URL and your network connection.

• Timed out after 15s talking to https://… The instance may be hibernating (PDI) or unreachable.

• Incident 'INC9999999' was not found on https://….

• Forbidden (403): the user lacks permission … or the update was rejected by a business rule. ServiceNow said: … (например, при разрешении инцидента без полей разрешения).

Заметки по дизайну

• ServiceNowClient оборачивает один httpx.AsyncClient (базовая аутентификация, JSON заголовки, таймаут) и предоставляет create_record / query_records / get_record_by_number / update_record. Все ошибки преобразуются в ServiceNowError с понятным сообщением.

• Инструменты получают клиента через get_client(); вызовите set_client(fake) в тестах, чтобы подменить на мок без обращения к сети.

• Записи запрашиваются с sysparm_display_value=all, поэтому метки состояния/срочности берутся из самого экземпляра, а не из жёстко заданной карты (псевдонимы с понятными именами используются только для ввода).

• mcp 2.x переименовал FastMCP в MCPServer; server.py импортирует то, что существует, поэтому работает как на 1.x, так и на 2.x.

Дымовой тест

Запустите на работающем экземпляре (создаст один инцидент):

uv run python -c "
import asyncio, server
async def main():
    c = await server.create_incident('MCP server smoke test', 'created by smoke test')
    print(c)
    print(await server.query_incidents(query_text='MCP server smoke test'))
    print(await server.update_incident(c['number'], work_notes='hello from MCP'))
asyncio.run(main())
"