energy-mcp

Сервер MCP для данных о спросе на электроэнергию в США и погоде. Он предоставляет данные в виде инструментов MCP, ресурсов и подсказок, работает локально через stdio и совместим с любым клиентом MCP: Claude Desktop, Claude Code, адаптерами MCP от LangChain или MCP Inspector.

Данные поставляются в виде небольшого SQLite-файла с реальными наблюдениями, так что вы можете клонировать репозиторий и запустить его без базы данных или API-ключа.

Python 3.11+ · MCP SDK 1.x (FastMCP) · MIT

Что такое MCP

MCP — это открытый протокол от Anthropic. Он предоставляет ИИ-клиенту единый стандартный способ вызова внешних инструментов и чтения внешних данных, вместо индивидуальной интеграции для каждого приложения. Сервер сообщает, что он предлагает, а клиент подключается и использует это. Серверы могут предлагать три типа объектов:

• Инструменты: функции, которые может вызывать модель.

• Ресурсы: данные только для чтения, которые клиент загружает как контекст.

• Подсказки: повторно используемые шаблоны, которые может выбрать пользователь.

Этот сервер предоставляет все три типа.

Related MCP server: euenergy-mcp

Инструменты, ресурсы и подсказки

Инструменты:

• list_regions(): доступные регионы с количеством строк и охватом по датам.

• query_demand(region, start, end, limit=168): почасовой спрос в МВт·ч за диапазон дат.

• daily_demand(region, start, end): среднесуточный, пиковый и минимальный спрос.

• peak_demand(region, start, end): час с самым высоким спросом.

• compare_regions(start, end, regions=None): средний и пиковый спрос по регионам.

• demand_vs_weather(region, start, end): суточный спрос, объединенный с температурой в этом регионе.

Ресурсы:

• schema://energy: текстовое описание таблиц.

• docs://coverage: какие регионы и даты загружены в данный момент.

Подсказки:

• analyze_demand(region): стартовый шаблон, который проводит по региону через инструменты.

Быстрый старт

Вам понадобится uv.

git clone https://github.com/visethchapman/energy-mcp
cd energy-mcp
uv run energy-mcp    # starts the server on stdio; it waits for a client

Чтобы опробовать инструменты в интерфейсе, используйте MCP Inspector:

uv run mcp dev src/energy_mcp/server.py

Подключение к клиенту

Claude Desktop

Добавьте это в claude_desktop_config.json (на macOS, ~/Library/Application Support/Claude/claude_desktop_config.json) и перезапустите Claude Desktop:

{
  "mcpServers": {
    "energy": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/energy-mcp", "run", "energy-mcp"]
    }
  }
}

Claude Code

claude mcp add energy -- uv --directory /absolute/path/to/energy-mcp run energy-mcp

Затем задавайте вопросы на естественном языке, и клиент выберет инструменты:

• "В какой энергосистеме США был самый высокий средний спрос в июле 2024 года?"

• "Когда был пик спроса в ERCOT в 2024 году, и насколько жарко было в Хьюстоне в тот день?"

• "Сравните спрос в CISO и PJM за первую неделю января."

Пример вывода

Реальные результаты из встроенных данных при вызове инструмента клиентом:

> peak_demand(region="ERCO", start="2024-01-01", end="2024-12-31")
{ "region": "ERCO", "period": "2024-08-20 23:00:00", "demand_mwh": 85544.0 }

> compare_regions(start="2024-07-01", end="2024-07-31")
[ {"region":"PJM",  "avg_mwh":109674.4, "peak_mwh":153121.0},
  {"region":"ERCO", "avg_mwh": 60200.6, "peak_mwh": 81200.0},
  {"region":"CISO", "avg_mwh": 32008.4, "peak_mwh": 44727.0},
  {"region":"NYIS", "avg_mwh": 21494.1, "peak_mwh": 28990.0} ]

> demand_vs_weather(region="ERCO", start="2024-07-01", end="2024-07-03")
[ {"day":"2024-07-01", "avg_mwh":67736.3, "tmax_c":37.8, "tmin_c":26.7},
  {"day":"2024-07-02", "avg_mwh":68463.9, "tmax_c":36.1, "tmin_c":27.2},
  {"day":"2024-07-03", "avg_mwh":68017.8, "tmax_c":34.4, "tmin_c":26.7} ]

demand_vs_weather — самый интересный. Спрос ERCOT растет с температурой в Хьюстоне летом (нагрузка кондиционеров), и инструмент возвращает оба ряда данных, чтобы модель могла указать на связь.

Данные

Все данные реальные, обрезаны до календарного 2024 года, чтобы файл был около 5 МБ.

SQLite-файл зафиксирован в репозитории, поэтому во время выполнения ничего не загружается. Чтобы пересобрать его или расширить диапазон дат (для этого нужен бесплатный API-ключ EIA):

uv run --extra build python scripts/build_sample_db.py --start 2023-01-01 --end 2024-12-31

Установите ENERGY_MCP_DB, чтобы указать серверу на другой SQLite-файл.

Безопасность

• Только чтение. База данных открывается с SQLite mode=ro, поэтому ни один инструмент не может записывать.

• Параметризованный SQL. Аргументы передаются как параметры, а не вставляются в строку запроса, поэтому они не могут внедрить SQL.

• Проверенные входные данные. Аргументы региона и даты проверяются до обращения к базе данных, а некорректный ввод возвращается в виде понятной ошибки, на которую модель может отреагировать.

• Для запуска не требуются секреты. Данные находятся в репозитории; ключ EIA нужен только для пересборки.

Разработка

uv run pytest
uv run mcp dev src/energy_mcp/server.py

Структура:

src/energy_mcp/
  server.py                   # FastMCP server: tools, resources, prompts
  db.py                       # read-only SQLite access
  data/energy_sample.sqlite   # bundled real data
scripts/build_sample_db.py    # how the sample was assembled
tests/test_tools.py

В проекте используется MCP SDK 1.x (API FastMCP), который применяется в текущей документации Claude Desktop и CLI mcp. SDK 2.x — это более новый редизайн.

Связанные проекты

energy-text2sql — это агент text-to-SQL, работающий с теми же данными EIA и NOAA. Те же данные, другой интерфейс: один отвечает на вопросы, генерируя SQL, а этот предоставляет данные в виде инструментов MCP.

Лицензия

MIT