能量MCP实验
一 实验性的 模型上下文协议（MCP） 集以下功能于一体的服务器：
- 通过配套应用非正式访问Vaillant集团能源数据
vaillant-client图书馆。 - 英国国家电网的碳强度预测来自 carbonintensity.org.uk 翻译成中文是“碳强度.英国”。这个网站主要提供有关碳排放强度的数据和信息。
重要提示： 这个项目是由克里斯蒂安·迪努（Cristian Dinu）出于研究和探索的目的而进行的。它是 未与Vaillant有关联或获得其认可 并且该软件在没有官方支持的情况下发布。请预期存在粗糙的边缘处理和可能的破坏性变更。
状态与限制
- Alpha级品质，公开，开源。
- 仅供本地实验使用——请在您自己的防火墙后部署。
- Vaillant 支持依赖于环境变量（
VAILLANT_API_*并且VAILLANT_SERIAL）并且目前正在阅读一本 单一的硬编码序列号 来自环境。 - 不包含任何秘密或序列号；您必须自行提供凭据。
- 部分威能终端设备仍不完整；错误信息尽可能以用户友好的方式呈现。
先决条件
- Python 3.11及以上版本
- 紫外线 用于依赖管理（推荐）。
- 访问Vaillant开发者门户：https://developer.vaillant-group.com/
- 威能API的凭证以及您系统本地存储的序列号（例如，存储在
.env文件）。
安装
# Clone the repository
git clone https://github.com/cdinu/energy-mcp-experimental.git
cd energy-mcp-experimental
# Install dependencies with uv
uv pip sync uv.lock
# (Optional) pull in the Vaillant extras directly from GitHub
uv pip sync --extra vaillant uv.lock
# (Recommended) install the experimental Vaillant client
uv pip install --editable ../vaillant-client # adjust path as needed填充本地（数据/内容） .env （Git 忽略）包含所需密钥：
VAILLANT_API_CLIENT=your-client-id
VAILLANT_API_SECRET=your-client-secret
VAILLANT_API_SUBSCRIBTION_KEY=your-subscription-key
VAILLANT_API_DIAGNOSTIC_SUBSCRIBTION_KEY=your-diagnostics-key
VAILLANT_API_CONTRACT_NUMBER=your-contract
VAILLANT_SERIAL=your-serial-number
USER_POSTCODE=SW1A 1AA # optional, used for carbon intensity tools运行服务器
通过标准输入输出启动服务器（对编辑器和终端很有用）：
uv run energy-mcp对于SSE传输（Claude Desktop所要求），利用模块入口点：
uv run python -m energy_mcp_experimental sse日志被写入到 energy-mcp-*.log 在工作目录中进行故障排除。
MCP客户端设置
- 克劳德桌面版
1. 定位 claude_desktop_config.json （例如在 macOS 上： ~/Library/Application Support/Claude/claude_desktop_config.json）。
1. 在（某处）下添加或更新条目 mcpServers 类似于：
{
"mcpServers": {
"energy-mcp-experimental": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/energy-mcp-experimental",
"--project",
"/absolute/path/to/energy-mcp-experimental",
"energy-mcp"
],
"env": {
"VAILLANT_SERIAL": "xxxxxxxxxxx",
"USER_POSTCODE": "DE1"
}
}
}
}调整路径（以及任何环境变量）以匹配您的设置。Claude Desktop 会自动通过标准输入输出启动服务器——无需 SSE 标志。
1. 重启 Claude 桌面应用以应用新的配置。
- VS Code（Claude 或 Cursor 扩展）
1. 安装支持MCP的扩展。 1. 在扩展设置中，添加一个新的本地MCP服务器配置，指向： - 命令： uv - 参数： run energy-mcp - 工作目录：仓库根目录。 1. 重启编辑器，以便扩展可以通过标准输入输出（stdio）启动服务器。
可用工具
vaillant_energy_consumption— 以用户友好的表格形式展示汇总及各时段的能源使用情况。vaillant_advanced_diagnostics— 详细诊断，对序列号进行遮蔽以保护隐私。vaillant_get_topology— 系统拓扑结构和设备元数据。vaillant_get_settings— 当前系统设置，包括时间表和覆盖设置。vaillant_get_state— 实时系统状态数据。current_uk_grid_carbon_intensity_in_postcode— 区域碳强度快照（需USER_POSTCODE或参数）。carbon_intensity_history_and_forecast_for_postcode— 未来24至48小时的当地天气预报。carbon_intensity_history_and_forecast_national— 国家级预测，以表格形式输出。current_national_generation_mix— 目前英国发电所用的燃料构成。
如果……，威能工具将发出有益的警告作为回应 vaillant-client 缺少依赖项。
______________________________________________________________________
与大型语言模型（MCP客户端）集成
这个（或“它”） 能源MCP实验 任何支持该协议的大型语言模型（LLM）客户端都可以使用该服务器 模型上下文协议以下是与Anthropic的API、Python集成的示例 agents 库（library）、Node.js 和 curl。
Anthropic（Python SDK）
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-sonnet-4-5",
max_tokens=1000,
messages=[{
"role": "user",
"content": "Show me the current state of my Vaillant heat pump."
}],
mcp_servers=[{
"type": "url",
"url": "https://your-deployed-mcp-address:8000/mcp",
"name": "vaillant-mcp",
"authorization_token": "YOUR_TOKEN"
}],
betas=["mcp-client-2025-04-04"]
)Python 代理 SDK（HTTP）
import asyncio
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp
from agents.model_settings import ModelSettings
async def main() -> None:
token = os.environ["MCP_SERVER_TOKEN"]
async with MCPServerStreamableHttp(
name="Vaillant MCP over HTTP",
params={
"url": "https://your-deployed-mcp-address:8000/mcp",
"headers": {"Authorization": f"Bearer {token}"},
"timeout": 10,
},
cache_tools_list=True,
max_retry_attempts=3,
) as server:
agent = Agent(
name="Assistant",
instructions="Use the Vaillant MCP tools to answer questions.",
mcp_servers=[server],
model_settings=ModelSettings(tool_choice="required"),
)
result = await Runner.run(agent, "Get the current carbon intensity forecast for SW1A 1AA.")
print(result.final_output)
asyncio.run(main())Python 代理 SDK（标准输入输出）
from pathlib import Path
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
current_dir = Path(__file__).parent
async with MCPServerStdio(
name="Vaillant MCP via stdio",
params={
"command": "uv",
"args": ["run", "energy-mcp"],
},
) as server:
agent = Agent(
name="Assistant",
instructions="Use the Vaillant MCP tools to answer questions.",
mcp_servers=[server],
)
result = await Runner.run(agent, "Retrieve my Vaillant heat pump settings.")
print(result.final_output)curl（注：在中文语境中，"curl"通常直接作为命令名使用，不翻译，但根据要求，可说明其为“用于传输数据的命令行工具”）
curl https://api.anthropic.com/v1/messages -H "Content-Type: application/json" -H "X-API-Key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -H "anthropic-beta: mcp-client-2025-04-04" -d '{
"model": "claude-sonnet-4-5",
"max_tokens": 1000,
"messages": [{"role": "user", "content": "Get the Vaillant system topology."}],
"mcp_servers": [
{
"type": "url",
"url": "https://your-deployed-mcp-address:8000/mcp",
"name": "vaillant-mcp",
"authorization_token": "YOUR_TOKEN"
}
]
}'Node.js（Anthropic SDK）
import { Anthropic } from '@anthropic-ai/sdk';
const anthropic = new Anthropic();
const response = await anthropic.beta.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 1000,
messages: [
{
role: "user",
content: "What is the latest energy consumption from my Vaillant heat pump?",
},
],
mcp_servers: [
{
type: "url",
url: "https://your-deployed-mcp-address:8000/mcp",
name: "vaillant-mcp",
authorization_token: "YOUR_TOKEN",
},
],
betas: ["mcp-client-2025-04-04"],
});______________________________________________________________________
发展
uv pip install --editable .[dev]
pytest许可证
在以下许可下发布 麻省理工学院许可证。