快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

python -m venv .venv

详细介绍

Qortal MCP服务器（Python）

概述

此存储库包含 只读Qortal MCP服务器 用Python实现。\ 它公开了精心策划的Qortal核心HTTP API子集（端口 12391)as LLM友好的工具，使代理（Codex、ChatGPT代理等）可以在链上查询 QDN数据没有任何签名或广播交易的能力。

服务器与Qortal Core节点一起运行，并充当安全、结构化的代理获取以下信息：

节点状态和版本
账户/余额/姓名信息
跨链贸易门户提供
QDN（Qortal数据网络）搜索元数据
组元数据（组列表、成员资格、邀请/请求/禁止）
聊天历史元数据（消息、计数、活动聊天）

所有写入/状态更改操作都永久超出范围。

状态

该项目尚处于早期开发阶段。

v1目标：最小但有用的工具集+稳定的Python服务器：

- 节点： get_node_status, get_node_info, get_node_summary, get_node_uptime - 账户/姓名： get_account_overview, get_balance, validate_address, get_name_info, get_names_by_address, get_primary_name, search_names, list_names, list_names_for_sale （默认情况下仅QORT；通过 include_assets +可选 asset_ids) - 交易： list_trade_offers （AT地址返回为 tradeAddress) - 隐藏交易： list_hidden_trade_offers （贸易门户网站报价失败，数量有限） - QDN： search_qdn （仅元数据；存在时包括名称/标识符） - 聊天： get_chat_messages, count_chat_messages, get_chat_message_by_signature, get_active_chats （可选 decode_text=true 安全时解码明文） - 组： list_groups, get_groups_by_owner, get_groups_by_member, get_group, get_group_members, get_group_invites_by_address, get_group_invites_by_group, get_group_join_requests, get_group_bans - 阻碍： get_block_at_timestamp, get_block_height, get_block_by_height, get_block_by_signature, get_block_height_by_signature, get_first_block, get_last_block, list_block_summaries, list_block_range - 交易： search_transactions, get_transaction_by_signature, get_transaction_by_reference, list_transactions_by_block, list_transactions_by_address, list_transactions_by_creator

get_account_overview 当前返回QORT余额和姓名；这 assetBalances v1中的字段故意留空，以避免大的有效载荷。其他省略或可选端点（例如，块签名者、铸币信息）列在 DESIGN.md.

计划：可选公共节点回退/NodePool（选择加入；默认为仅本地）。看 DESIGN.md 获取策略和配置说明。

第一个实施里程碑仅关注 get_node_status 和 get_account_overview，然后从那里扩展。

有关完整详细信息，请参阅 DESIGN.md.

安全模型（简称）

只读 –无签名、无广播、无POST/PUT/DELETE调用。
只有a 列入白名单的GET端点集 在...之下 /admin, /addresses,

/names, /crosschain/tradeoffers, /arbitrary/search，以及一小部分的 /assets 将永远被使用。

工具输入经过验证（地址、名称、服务代码、限制等）。
对LLM的输出进行修剪和归一化（没有巨大的二进制blob，没有日志，

没有敏感节点细节）。

Qortal Core API密钥（如果需要）保存在服务器端，并且从不返回

对于来电者。

进程启动时读取配置；集 QORTAL_* 在启动服务器之前执行env变量（重新启动以应用更改）。

完整的安全模型记录在 DESIGN.md 并通过规则在 AGENTS.md.

公共节点回退（选择加入，实验性）

默认行为仍然是单节点/本地。必须明确启用回退到公共节点。
通过env启用： QORTAL_ALLOW_PUBLIC_FALLBACK=true 加上逗号分隔 QORTAL_PUBLIC_NODES 列表（例如。， https://api.qortal.org).可选调整： QORTAL_FALLBACK_COOLDOWN_SECONDS （默认值约为30）， QORTAL_FALLBACK_HEALTH_CHECK_PATH （默认值 /blocks/height), QORTAL_FALLBACK_HEALTH_CHECK_TIMEOUT （默认值~2s）。
政策：初级优先；仅在网络错误（连接/超时）时重试另一个节点。任何真正的HTTP响应（包括401/4xxx/5xx）都会停止重试。最近发生故障的节点会被跳过进行短暂的冷却（默认约30秒）。
API密钥：只发送给受信任的本地节点；从未转发到公共节点。由于缺少身份验证，管理端点在回退时仍可能失败。
信任说明：公共节点更改只读数据的信任模型；只有当你接受这种权衡时，才能启用。看 DESIGN.md 了解详情。

高层体系结构

Python 3.11+

HTTP服务器：FastAPI+Uvicorn（或等效的ASGI服务器）

Qortal的HTTP客户端： httpx

内部布局（有待完善）：

  qortal_mcp/
    __init__.py
    config.py           # base URL, API key path, timeouts, limits
    qortal_api/
      __init__.py
      client.py         # thin wrappers around whitelisted Qortal HTTP endpoints
    tools/
      __init__.py
      node.py           # node status / info tools
      account.py        # account + balance + names tools
      names.py          # name system helpers
      trade.py          # Trade Portal tools
      qdn.py            # QDN / arbitrary search tools
    server.py           # FastAPI app wiring tools to HTTP routes or MCP interface

每个工具功能负责：

验证输入
呼叫一个或多个 qortal_api.client 助手
将原始Qortal响应映射为LLM的紧凑JSON结果
处理和规范错误

看 DESIGN.md 了解每个工具及其底层Qortal的详细信息端点。

需求

python 3.11+
跑步核心启用了HTTP API的节点（默认值

http://localhost:12391)

如果您的Core需要API密钥 /admin/* 端点，确保MCP

服务器可以读取它（例如从 apikey.txt或环境）。

快速启动（一旦实施）

# 1. Clone the repo
git clone https://github.com//qortal-mcp-python.git
cd qortal-mcp-python

# 2. Create a virtualenv and install dependencies
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt

# 3. Configure Qortal Core connection (defaults usually OK)
#    e.g. edit config file or set environment variables as described in DESIGN.md

# 4. Run the server (example – adjust module/path once implemented)
uvicorn qortal_mcp.server:app --reload

# (Optional) Quick sanity check against your local Core node
# Override QORTAL_SAMPLE_ADDRESS to another on-chain address if desired.
python scripts/sanity_check.py

# (Optional) Run unit tests
pip install -r requirements-dev.txt
pytest

# (Optional) Live integration tests (require a running Core node)
# Set LIVE_QORTAL=1 and optionally QORTAL_SAMPLE_ADDRESS / QORTAL_SAMPLE_NAME
LIVE_QORTAL=1 pytest tests/test_live_integration.py

## HTTP usage examples

With the server running (default `http://localhost:8000`):

Health

curl http://localhost:8000/health

Metrics snapshot

curl http://localhost:8000/metrics

Node status

curl http://localhost:8000/tools/node_status

Account overview

curl http://localhost:8000/tools/account_overview/QgB7zMfujQMLkisp1Lc8PBkVYs75sYB3vV

Validate address (no Core call)

curl http://localhost:8000/tools/validate_address/QgB7zMfujQMLkisp1Lc8PBkVYs75sYB3vV

Name info

curl http://localhost:8000/tools/name_info/AGAPE

Trade offers (limit=3)

curl "http://localhost:8000/tools/trade_offers?limit=3"

Groups (list first 5)

curl "http://localhost:8000/tools/groups?limit=5"

Group detail + members

curl "http://localhost:8000/tools/group/1" curl "http://localhost:8000/tools/group/1/members?limit=10"

Chat (messages between two addresses)

curl "http://localhost:8000/tools/chat/messages?involving=Qaddress1&involving=Qaddress2&limit=5"

Chat with decoded plaintext (when not encrypted)

curl "http://localhost:8000/tools/chat/messages?involving=Qaddress1&involving=Qaddress2&limit=5&decode_text=true"

Hidden trade offers (limit=3)

curl "http://localhost:8000/tools/hidden_trade_offers?limit=3"

Account overview with bounded assets

curl "http://localhost:8000/tools/account_overview/QgB7zMfujQMLkisp1Lc8PBkVYs75sYB3vV?include_assets=true&asset_ids=1&asset_ids=2"


## MCP集成（初始化+工具）

MCP网关位于 `POST /mcp` 并支持MCP初始化握手
加上标准工具方法。

- **协议版本**: `2025-03-26` （回应客户）
- **支持的方法**:
  - `initialize` → 回报 `protocolVersion`, `serverInfo`, `capabilities.tools`
  - `tools/list` 或 `list_tools` → 返回工具目录
  - `tools/call` 或 `call_tool` → 按名称调用工具

示例 `initialize` 调用调试：

curl -sS -X POST http://127.0.0.1:8000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": { "name": "debug-client", "version": "0.0.1" } } }'


工具调用（初始化后）：

{"jsonrpc": "2.0", "id": 2, "method": "tools/list"} {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "validate_address", "arguments": {"address": "Q..."}}}


工具响应包括 `content` 带a的数组 `text` 项目加a
`structuredContent` JSON结果的副本。工具执行错误集
`isError: true` 并将消息作为文本内容返回。协议级故障
使用JSON-RPC `error` 现场。

显示： `mcp-manifest.json` 点在 `http://localhost:8000/mcp` 带名字
`qortal-mcp-server` 和版本 `0.1.0`。更新终结点以供远程使用。

## 关于速率限制和日志记录的说明

- 一个简单的每工具速率限制器（令牌桶）默认为~5个请求/秒
  每个工具都可以保护底层Qortal节点。通过以下方式进行调整 `QortalConfig.rate_limit_qps`.
- 日志记录最少，避免了秘密。通过以下方式调整日志级别 `QORTAL_MCP_LOG_LEVEL`.
- 回复包括 `X-Request-ID` 用于跟踪的标头。
- 日志格式可以通过以下方式切换为JSON `QORTAL_MCP_LOG_FORMAT=json`.每个工具
  速率限制可以通过以下代码设置 `per_tool_rate_limits` 如果需要的话。
- `/metrics` 返回进程中计数器（请求、速率限制计数、每个工具的成功/错误）；对于多工设置，请从外部聚合。

## 测试

- 单元测试： `pytest` （或 `pytest --cov=qortal_mcp --cov=tests --cov-report=term-missing` 安装后 `requirements-dev.txt` 其中包括 `pytest-cov`).
- 实时集成（需要正在运行的Qortal节点）： `LIVE_QORTAL=1 pytest tests/test_live_integration.py` （可选设置 `QORTAL_SAMPLE_ADDRESS` / `QORTAL_SAMPLE_NAME`).

## 部署说明

- 与uvicorn或gunicorn+uvicorn工人一起跑步，例如：
  - `uvicorn qortal_mcp.server:app --host 0.0.0.0 --port 8000`
  - `gunicorn -k uvicorn.workers.UvicornWorker -w 2 qortal_mcp.server:app`
- 每个流程都有速率限制和度量；如果您运行多个worker或在反向代理后面运行，请考虑外部聚合和/或调整 `per_tool_rate_limits`.
- 在反向代理（nginx/caddy/traefik）处终止TLS，如果暴露在本地主机之外，则限制对受信任客户端的访问。
- `/metrics` 返回进程内计数器（请求、速率限制计数、每个工具的成功/错误）。

Once running, the server can be wired into your LLM tooling as an MCP server or as an HTTP tool host, depending on your integration.

Available tool routes (v1)

GET /health
GET /metrics
GET /tools/node_status
GET /tools/node_info
GET /tools/account_overview/{address}
GET /tools/balance/{address}?assetId=0
GET /tools/validate_address/{address}
GET /tools/name_info/{name}
GET /tools/names_by_address/{address}?limit=...
GET /tools/trade_offers?limit=...
GET /tools/qdn_search?address=...&service=...&limit=...

Roadmap (short)

Milestone 1

- Project skeleton - qortal_api.client - get_node_status, get_account_overview

Milestone 2

- Remaining v1 tools (get_node_info, get_name_info, etc.) - More robust error handling, logging, and tests

Milestone 3

- Example agent / MCP integration configs - Optional extended tools (DEX views, QDN convenience tools)

See DESIGN.md for the current authoritative plan.

目录标签

PythonPython服务金融数据区块链代理本地部署只读APILLM工具集成Qortal数据查询

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

api-key

运行时（runtime，运行环境）

Python

工具数量（toolCount，工具数）

12

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdioapi-key部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

MCP World

mcpworld.com

/detail/f43f2942af27b6fac92ef2eff17e26ec

一个为LLM工具提供Qortal区块链数据只读访问的Python服务代理，适用于查询节点状态、账户信息、交易数据等场景。

继续浏览同类 MCP

更多金融服务 MCP（2,622）返回 MCP 目录

上一个 MCP

qng MCP

qng的mcp服务器支持模型上下文协议（MCP）协议，用于与区块链交互和查询。

下一个 MCP

Qoyyuum MCP

全面解析MCP Metatrader5 ServerMCP Server的核心功能、安装配置和实用案例。作为顶级Model Context Protocol服务器，MCP Metatrader5 Server能让AI助手访问实时数据、执行操作，为您提供更智能的工作体验和自动化解决方案。

Qortal MCP Server