预构建工具 • 联系我们

Arcade MCP 服务器框架

• 要查看使用 Arcade MCP 服务器框架（本仓库）构建的示例服务器，请参阅我们的 示例。

• 要了解更多关于 Arcade MCP 服务器框架（本仓库）的信息，请参阅我们的 Arcade MCP 文档。

• 要了解 Arcade.dev 的其他产品和服务，请参阅我们的 文档。

顺便说一句，如果你喜欢这个项目，别忘了给我们点个赞哦！

快速入门：创建一个新的服务器

最快捷的入门方式是使用 arcade new CLI 命令，它会创建一个完整的 MCP 服务器项目：

# 安装 CLI 工具
uv tool install arcade-mcp

# 创建一个新的服务器项目
arcade new my_server

# 进入项目目录
cd my_server/src/my_server

这将生成一个包含以下内容的项目：

• server.py - 主服务器文件，包含 MCPApp 和示例工具

• pyproject.toml - 依赖项和项目配置

• .env.example - 示例 .env 文件，其中包含 server.py 中生成的一个工具所需的密钥

生成的 server.py 包含完善的命令行参数处理以及三个示例工具：

#!/usr/bin/env python3
"""simple_server MCP 服务器"""

import sys
from typing import Annotated

import httpx
from arcade_mcp_server import Context, MCPApp
from arcade_mcp_server.auth import Reddit

app = MCPApp(name="simple_server", version="1.0.0", log_level="DEBUG")


@app.tool
def greet(name: Annotated[str, "要问候的人的名字"]) -> str:
    """用名字问候某人。"""
    return f"你好，{name}！"


# 要在本地使用此工具，你需要在 .env 文件中设置密钥，或者将其作为环境变量。
@app.tool(requires_secrets=["MY_SECRET_KEY"])
def whisper_secret(context: Context) -> Annotated[str, "密钥的最后4位字符"]:
    """揭示密钥的最后4位字符"""
    # 密钥会在运行时注入到上下文中。
    # LLM 和 MCP 客户端无法看到或访问你的密钥。
    # 你可以将密钥定义在 .env 文件中。
    try:
        secret = context.get_secret("MY_SECRET_KEY")
    except Exception as e:
        return str(e)

    return "密钥的最后4位字符是：" + secret[-4:]

# 要在本地使用此工具，你需要安装 Arcade CLI（uv tool install arcade-mcp），然后运行 'arcade login' 进行认证。
@app.tool(requires_auth=Reddit(scopes=["read"]))
async def get_posts_in_subreddit(
    context: Context, subreddit: Annotated[str, "子版块的名字"]
) -> dict:
    """从特定子版块获取帖子"""
    # 规范化子版块名称
    subreddit = subreddit.lower().replace("r/", "").replace(" ", "")

    # 准备 httpx 请求
    # OAuth 令牌会在运行时注入到上下文中。
    # LLM 和 MCP 客户端无法看到或访问你的 OAuth 令牌。
    oauth_token = context.get_auth_token_or_empty()
    headers = {
        "Authorization": f"Bearer {oauth_token}",
        "User-Agent": "{{ toolkit_name }}-mcp-server",
    }
    params = {"limit": 5}
    url = f"https://oauth.reddit.com/r/{subreddit}/hot"

    # 发起请求
    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers, params=params)
        response.raise_for_status()

        # 返回响应
        return response.json()

# 使用指定传输方式运行
if __name__ == "__main__":
    # 从命令行参数获取传输方式，默认为 "stdio"
    # - "stdio"（默认）：用于 Claude Desktop、CLI 工具等的标准 I/O。
    #   可以直接支持需要身份验证或密钥的工具。
    # - "http"：用于 Cursor、VS Code 等的 HTTPS 流式传输。
    #   不支持需要身份验证或密钥的工具，除非服务器通过 'arcade deploy' 部署，或者在 Arcade 开发者仪表板中将服务器类型设置为 'Arcade'。
    transport = sys.argv[1] if len(sys.argv) > 1 else "stdio"

    # 运行服务器
    app.run(transport=transport，host="127.0.0.1"，port=8000)

这种方法为你提供了：

• 完整的项目设置 - 一切只需一条命令即可完成

• 最佳实践 - 使用 pyproject.toml 进行规范的依赖管理

• 示例代码 - 从常见模式的实际示例中学习

• 生产就绪 - 结构化设计，便于扩展和部署

运行你的服务器

你可以直接使用 Python 运行你的服务器：

# 使用 stdio 传输方式（默认）
uv run server.py

# 使用 http 传输方式，通过命令行参数指定
uv run server.py http

# 或者直接使用 python
python server.py http
python server.py stdio

你的服务器将会启动并监听连接。如果使用 HTTP 传输方式，你可以在 http://127.0.0.1:8000/docs 访问 API 文档。

配置 MCP 客户端

服务器启动后，将其连接到您喜爱的 AI 助手：

arcade configure claude # 配置 Claude Desktop 以连接到当前目录下的 stdio 服务器
arcade configure cursor --transport http --port 8080 # 配置 Cursor 以连接到本地 HTTP 服务器，端口为 8080
arcade configure vscode --entrypoint my_server.py # 配置 VSCode 以连接到 stdio 服务器，该服务器将在直接执行 my_server.py 时启动

从源代码安装此仓库

git clone https://github.com/ArcadeAI/arcade-mcp.git && cd arcade-mcp && make install

支持与社区

• Discord： 加入我们的 Discord 社区，获取实时支持与交流。
• GitHub： 您可以在 Arcade GitHub 仓库 上贡献代码或报告问题。
• 文档： 在 Arcade 文档 中查找深入指南和 API 参考。

Arcade MCP Server Framework 快速上手指南

Arcade MCP 是一个用于构建模型上下文协议（MCP）服务器的 Python 框架，帮助开发者快速创建连接 AI 助手与外部工具/数据的桥梁。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)
• Python 版本：Python 3.9 或更高版本
• 包管理工具：推荐使用 uv (高速 Python 包管理器)，也可使用标准 pip
• 网络环境：需能访问 GitHub 和 PyPI (国内用户若遇下载缓慢，可配置国内镜像源)

提示：如果您尚未安装 uv，可以通过以下命令安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装步骤

最快捷的方式是使用 Arcade 提供的 CLI 工具来初始化和运行项目。

1. 安装 CLI 工具

使用 uv 安装 arcade-mcp 命令行工具：

uv tool install arcade-mcp

2. 创建新项目

使用 arcade new 命令生成一个完整的 MCP 服务器项目结构：

arcade new my_server

3. 进入项目目录

切换到生成的项目源码目录：

cd my_server/src/my_server

此时，您将拥有以下核心文件：

• server.py: 包含 MCP 应用入口和示例工具的主文件。
• pyproject.toml: 项目依赖和配置。
• .env.example: 环境变量示例文件（用于配置密钥）。

基本使用

1. 运行服务器

项目默认支持两种传输模式：stdio (标准输入输出，适用于 Claude Desktop 等) 和 http (适用于 Cursor、VS Code 等)。

启动 stdio 模式 (默认):

uv run server.py

启动 http 模式:

uv run server.py http

注：使用 HTTP 模式时，可在浏览器访问 http://127.0.0.1:8000/docs 查看 API 文档。

2. 代码示例解析

生成的 server.py 包含了三个典型工具示例，展示了框架的核心能力：

• 基础工具: 简单的字符串处理 (greet)。
• 密钥管理: 安全地读取环境变量中的敏感信息 (whisper_secret)，LLM 无法直接看到密钥明文。
• OAuth 认证: 处理需要用户授权的第三方 API 调用 (get_posts_in_subreddit 示例了 Reddit 集成)。

核心代码结构如下：

from arcade_mcp_server import Context, MCPApp

app = MCPApp(name="simple_server", version="1.0.0", log_level="DEBUG")

@app.tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

@app.tool(requires_secrets=["MY_SECRET_KEY"])
def whisper_secret(context: Context) -> str:
    """Reveal the last 4 characters of a secret"""
    secret = context.get_secret("MY_SECRET_KEY")
    return "The last 4 characters of the secret are: " + secret[-4:]

3. 连接 AI 客户端

服务器运行后，使用 CLI 工具自动配置您的 AI 编辑器或助手：

配置 Claude Desktop (stdio 模式):

arcade configure claude

配置 Cursor (http 模式):

arcade configure cursor --transport http --port 8000

配置 VS Code (stdio 模式):

arcade configure vscode --entrypoint my_server.py

配置完成后，重启对应的 AI 客户端，即可在对话中调用您编写的工具。