Elfa MCP

Elfa MCP

适用于 Elfa API 的 Model Context Protocol 服务，涵盖加密货币和股票的 API v3 事件、持仓与排名，Auto（一种会监测市场并在条件满足时触发操作的条件引擎），以及来自 X 和 Telegram 的加密货币社交情报。

可与任何 MCP 客户端搭配使用：登录托管服务，或使用 API 密钥在本地运行。

安装

托管服务，使用 Elfa 登录

在客户端中添加 https://mcp.elfa.ai/mcp 作为远程 MCP 服务，然后在浏览器中使用你的 dev.elfa.ai 账号授权。无需复制密钥，也无需安装任何内容。如果客户端无法登录，请改为在本地运行服务。设置步骤请参阅 MCP 指南。

本地运行，使用 API 密钥

在 dev.elfa.ai 获取 API 密钥。无需安装步骤，npx 会按需获取服务。

一键添加

Claude Desktop

从最新版本下载 elfa-mcp-<version>.mcpb 并打开。Claude Desktop 会安装它，提示你输入 API 密钥，并保持更新。无需进行其他配置。

Claude Code

claude mcp add elfa --env ELFA_API_KEY=your-key -- npx -y @elfa-ai/mcp

Cursor、VS Code、Claude Desktop 和其他客户端

{
  "mcpServers": {
    "elfa": {
      "command": "npx",
      "args": ["-y", "@elfa-ai/mcp"],
      "env": {
        "ELFA_API_KEY": "your-key"
      }
    }
  }
}

VS Code 使用 "servers"，而不是 "mcpServers"。其他设置均相同。

询问 “现在加密货币市场上有什么热门趋势？”，确认是否正常运行。

配置

变量	必需	用途
ELFA_API_KEY	是	对每个请求进行身份验证
ELFA_TIMEOUT	否	请求超时时间，单位为毫秒，默认值为 120000
ELFA_RETRIES	否	失败时的重试次数，默认值为 0
ELFA_MCP_MAX_RESPONSE_CHARS	否	响应大小上限，默认值为 60000
ELFA_EXTRA_HEADERS	否	要发送至上游的额外请求头 JSON 对象，适用于代理和非生产环境

上游请求会使用 User-Agent: elfa-mcp/<version> (<transport>; client=<app>) 标识自身。使用 stdio 时，<app> 是握手信息中的 MCP 客户端名称和版本；使用 HTTP 时，则是发起连接的客户端自身的 User-Agent 请求头。若要发送自己的请求头，请在 ELFA_EXTRA_HEADERS 中设置 User-Agent。

故意将超时时间设得较长，并关闭重试。解读类端点由大模型驱动，耗时可能超过一分钟；而且每次尝试都会消耗额度，因此静默重试会让你为一次看不见的调用再次付费。只有在调用低成本的测量类端点时，才提高 ELFA_RETRIES。

有些 MCP 客户端会设置自己的超时时间，通常约为 60 秒。narratives 和 market_chat 的处理时间可能超过该限制；即使客户端先放弃，请求仍会完成并产生费用。

工具

共有 16 个工具，对应所有已记录的 /v2 和 /v3 操作。

工具	模式	费用	功能
api_status	读取	免费	检查 API 密钥等级、额度使用情况和剩余请求数，以及事件、市场和调用的历史回溯范围。还会确认 API 是否可访问。
entities	读取	PAYG 和 Grow 用户免费，截止至 2026 年 10 月 31 日	将股票代码、$cashtag、名称、@handle、合约地址、CoinGecko id、FIGI 或 CIK 解析为事件和调用所使用的实体 ID。仅进行精确匹配，不是搜索。
events	读取	PAYG 和 Grow 用户免费，截止至 2026 年 10 月 31 日	了解加密货币和股票市场正在发生的事情。level=events 查看发生了什么以及价格如何反应；level=storylines 查看跨越多日的单项进展；level=arcs 查看归入更大趋势的故事线。支持按主题搜索。
market	读取	PAYG 和 Grow 用户免费，截止至 2026 年 10 月 31 日	查看加密货币或股票市场的全局概况。view=mindshare 按关注度占比排列资产；view=call_book 按小时展示大众的看多／看空倾向；view=trending_contracts 按提及合约地址的帖子数量排序。
calls	读取	PAYG 和 Grow 用户免费，截止至 2026 年 10 月 31 日	查看账号在帖子中采取的仓位。level=calls 查看每条建仓或调整仓位的帖子；level=episodes 查看从开仓到平仓的每个仓位及作者的过往表现；level=positioning 查看当前对单项资产的未平仓多头和空头仓位。
top_accounts	读取	PAYG 和 Grow 用户免费，截止至 2026 年 10 月 31 日	按影响力（其他账号与其互动的程度）排列 X 账号；也可使用 metric，按其作为市场观点发布者的过往表现（alphaScore、hitRate、avgReturn）排序。
auto_build	读取	1 加大模型用量	将自然语言监控请求转换为 EQL 查询。返回待验证和启用的草稿；此工具本身不会启用查询。
auto_validate	读取	免费	检查 EQL 语法并在启用前估算费用，或检查某个交易场所是否有某个代码的数据。
auto_query	读取	免费	Auto 的读取端：列出查询、轮询某个查询，以及查看其执行记录和大模型会话。
auto_query_write	写入	创建需支付 5 加大模型用量；取消或删除免费	启用、取消或删除 Auto 查询。启用后的查询会在无人值守的情况下运行，并在满足条件时触发其操作。
auto_draft	读取	免费	Auto 草稿的读取端：列出已保存的草稿并查看某个草稿。草稿是尚未启用的查询，不会进行评估或触发操作。
auto_draft_write	写入	免费，但转换操作的费用与创建查询相同	创建、更新、删除或启用 Auto 草稿。转换草稿会将其启用为无人值守运行的实时查询。
mentions	读取	每次调用 1	查看来自 X 和 Telegram 的社交提及。mode=top 按互动量排列某个股票代码的提及；mode=search 按关键词或账号筛选；mode=news 返回代币新闻动态，即来自标记为新闻来源的账号的 X 帖子，而非新闻媒体发布的文章。
trending	读取	每次调用 1	查看正在获得社交关注的内容。scope=tokens 用于股票代码；scope=contracts_twitter 或 scope=contracts_telegram 用于合约地址。
narratives	读取	每次调用 5	提供带来源链接的文字叙事分析。scope=market 提取全市场叙事；scope=keywords 汇总特定关键词的相关事件。
market_chat	读取	费用因速度而异	请求文字版市场分析。支持对话式聊天、宏观概览、快速摘要、代币简介、代币分析和账号分析。

未作为工具公开：

• chat-stream-v2 — 工具调用只返回一个结果，因此流式传输没有额外作用。market_chat 涵盖相同的分析。
• auto-stream-queries-v2 — 长时间运行的流没有对应的工具。请使用 auto_query 轮询。
• auto-stream-query-v2 — 长时间运行的流没有对应的工具。请使用 auto_query 轮询。
• getAccountSmartStats-v2 — API 将于 2026 年 10 月 28 日下线此端点，因此 account_stats 工具已移除。没有工具能返回其账户级数据；mentions 配合 mode=search 可返回按帖子统计的互动指标及发帖账户。

部分工具取决于套餐：目前，market_chat 和 API v3 工具需要高于免费套餐的套餐。服务启动时（stdio）或每次请求时（HTTP；每个密钥缓存一分钟），服务都会从 /v2/key-status 读取密钥的权限范围。套餐不包含的工具仍会列出，但其描述会说明需要更高级别的套餐；调用时会返回升级链接，不会调用 API，也不会消耗额度。如果无法在 3 秒内读取权限范围，所有工具都会照常列出，并由 API 决定。

对于能够使用 SSE 的应用，流式端点仍可通过 SDKs 使用。

API v3

entities、events、market、calls 和 top_accounts 使用 API v3：事件、故事线和叙事弧；调用订单簿、市场关注度和热门合约；调用、调用事件和仓位；排名靠前的账户。它们支持加密货币和股票，在 Pay-as-you-go 和 Grow 套餐中免费开放至 2026 年 10 月 31 日，并向 Enterprise 密钥开放。

• 筛选条件使用实体 ID，而非股票代码。请先使用 entities 解析资产，并重复使用该 ID。
• 时间使用 Unix 秒。毫秒会被拒绝。
• 密钥可读取的历史时间范围取决于其套餐。api_status 会通过 historyFrom 返回该范围。

与原始 API 的区别

这些工具刻意不沿用 API 的所有默认值，因为 Agent 需要为上下文中的冗余信息付费。

	API	此处	原因
pageSize	根据端点不同，为 10 到 50，最大 100	10	逐页获取，而非一次性拉取全部内容
v3 工具的 limit	根据端点不同，为 10 或 50，最大 30 或 200	10	使用 cursor 分页，而非一次性拉取全部内容
聊天的 speed	expert	fast	默认成本更低；需要深入分析时可选择 expert
提及字段	完整记录	高信号字段	设置 verbosity: "detailed" 获取其余字段
大型响应	完整返回	精简至适当长度，并附带说明	避免一次调用就填满上下文窗口

每个值仍可在每次调用时设置：pageSize 最大接受 100，limit 最大可设为相应端点的上限。

Auto

Auto 查询会在无人值守的情况下运行。查询启用后，会持续评估并执行其操作，无需再次确认。

流程分为三步：

1. auto_build — 用通俗语言描述监控内容，获取 EQL
2. auto_validate — 检查语法并获取额度成本
3. auto_query_write — 启用查询

操作可以向你发送通知、调用 webhook、向 Telegram 机器人发送消息，或运行大模型分析。

MCP 不提供推送通道。请使用 method=get 轮询 auto_query，并在两次调用之间等待其返回的 pollAfterSeconds。

远程服务

同一服务也可通过 Streamable HTTP 运行，以用于托管部署：

ELFA_MCP_TRANSPORT=http ELFA_MCP_PORT=3000 npx -y @elfa-ai/mcp

它是无状态的——不使用会话，每个请求都会启动一个服务实例，可安全地置于负载均衡器之后。凭据来自 x-elfa-api-key 请求标头，若无则回退到环境变量，也可以通过 OAuth 登录获取（见下文）。

默认启用 DNS 重绑定保护。服务只接受其绑定的环回名称——localhost:PORT 和 127.0.0.1:PORT——这涵盖了上述本地运行方式，不包括其他情况。任何通过不同 Host 响应的部署都必须列出其提供服务的值：

ELFA_MCP_ALLOWED_HOSTS=mcp.example.com

这包括公共域名、反向代理，以及将端口映射到与服务绑定端口不同端口的容器。列表未涵盖的 Host 将被拒绝，并返回 403。

变量	必需	用途
ELFA_MCP_TRANSPORT	否	使用 http 通过 Streamable HTTP 提供服务，默认值为 stdio
ELFA_MCP_HOST	否	绑定地址，默认值为 127.0.0.1
ELFA_MCP_PORT	否	绑定端口，默认值为 3000
ELFA_MCP_ALLOWED_HOSTS	否	以逗号分隔的 Host 允许列表，默认值为已绑定的环回名称
ELFA_MCP_ALLOWED_ORIGINS	否	以逗号分隔的 Origin 允许列表
ELFA_MCP_OPENAI_APPS_CHALLENGE	否	来自 OpenAI 插件门户的域名验证令牌，以纯文本形式在 /.well-known/openai-apps-challenge 提供

如果浏览器直接调用服务，也请设置 ELFA_MCP_ALLOWED_ORIGINS。它是对 Host 允许列表的补充，而非替代：重绑定请求属于同源请求，因此不会携带供该列表检查的 Origin 标头，而 Host 标头是唯一仍会指向攻击者域名的标头。

OAuth 登录

托管服务可以让客户端通过浏览器登录，而无需发送 API 密钥。设置 ELFA_MCP_AUTH=oauth 后，服务将依据 MCP 授权规范成为 OAuth 资源服务器：

1. 不带凭据的请求会收到 401 和 WWW-Authenticate 挑战。
2. 挑战会将客户端指向 /.well-known/oauth-protected-resource/mcp 下的受保护资源元数据。
3. 该元数据会列出授权服务器，用户可在该服务器登录。
4. 随后客户端发送 Authorization: Bearer <token>。
5. 服务会通过授权服务器的令牌自省端点检查令牌。该端点会返回请求所用的 Elfa API 密钥，因此令牌永远不会到达 Elfa API。

ELFA_MCP_TRANSPORT=http \
ELFA_MCP_AUTH=oauth \
ELFA_MCP_RESOURCE_URL=https://mcp.example.com/mcp \
ELFA_OAUTH_ISSUER=https://auth.example.com \
ELFA_OAUTH_INTROSPECTION_URL=https://auth.example.com/introspect \
ELFA_OAUTH_INTROSPECTION_TOKEN=... \
ELFA_MCP_ALLOWED_HOSTS=mcp.example.com \
npx -y @elfa-ai/mcp

变量	OAuth 模式下必需	用途
ELFA_MCP_AUTH	是	设置为 oauth 以启用，默认值为 apikey
ELFA_MCP_RESOURCE_URL	是	此端点的规范 URL。令牌必须正好针对该值签发
ELFA_OAUTH_ISSUER	是	元数据中列出的授权服务器
ELFA_OAUTH_INTROSPECTION_URL	是	检查令牌的地址
ELFA_OAUTH_INTROSPECTION_TOKEN	是	发送到令牌自省端点的 Bearer 令牌
ELFA_OAUTH_SCOPES	否	以逗号分隔的待公布作用域，默认值为 elfa

注意：

• OAuth 模式下，x-elfa-api-key 标头仍然有效。
• OAuth 模式会忽略 ELFA_API_KEY，因此没有凭据的调用方绝不会以服务自身的密钥运行。
• 有效令牌最多缓存一分钟，从而限制已撤销令牌继续生效的时间。

安全

api_status 是区分身份验证问题与额度问题最快的方法。

提及、新闻和叙事会返回任何人都能撰写的第三方社交文本，事件内容根据这些文本撰写，v3 工具则包含第三方资产、账户和频道名称。服务会在每个响应中将其标记为不可信，并在服务指令中告知模型应将其视为数据。在让 Agent 根据这些内容继续调用 auto_query_write 之前，请牢记这一点。

开发

npm install
npm run build
npm run verify

npm run verify 会运行类型检查、测试、规范差异检查和文档检查。

manifest.json 将每个已记录的 API 操作映射到负责处理它的工具。如果 API 新增了服务未处理的操作，npm run check:drift 就会失败。上方的工具表由同一个文件通过 npm run docs:tools 生成。

链接

• 文档
• API 密钥
• TypeScript SDK

许可证

MIT