项目简介

Asana MCP Railway 服务器是一个将Asana项目管理功能封装成 Model Context Protocol (MCP) 标准服务的后端应用。它允许AI（如Claude Code）通过标准化的JSON-RPC协议与Asana进行交互，管理任务、项目、部门等。该服务器支持OAuth 2.0认证，确保安全的多用户访问，并针对Railway平台进行了优化部署。

主要功能点

安全认证: 支持OAuth 2.0 (带PKCE) 认证，保障用户数据安全，并支持多用户会话管理。
42项Asana工具: 提供与官方Asana MCP完全一致的42项工具，覆盖任务创建、查询、更新、删除、项目管理、子任务、依赖关系、标签、部门管理等所有核心Asana操作。
多用户支持: 能够管理多个用户的Asana令牌，实现并发的多LLM会话。
自动令牌刷新: 后台自动刷新Asana访问令牌，确保服务持续可用。
HTTP/SSE传输: 通过HTTP和SSE (Server-Sent Events) 协议与LLM客户端通信，适用于远程访问。
部署简便: 提供Docker配置，可轻松部署到Railway等云平台。
内置技能指导: 包含一个名为 'asana-mcp-field-guide' 的Claude Code技能，为LLM提供Asana API使用最佳实践，优化查询和减少令牌消耗。

安装步骤

在本地计算机上运行该服务器：

克隆仓库: 打开终端或命令行工具，执行以下命令克隆项目：

git clone https://github.com/MagicTurtle-s/asana-mcp-railway.git
cd asana-mcp-railway

创建并激活Python虚拟环境: 这是一个最佳实践，用于隔离项目依赖。

python -m venv venv
# 对于 macOS/Linux 用户:
source venv/bin/activate
# 对于 Windows 用户:
venv\Scripts\activate

安装项目依赖:

pip install -r requirements.txt

配置Asana OAuth应用:
- 访问 Asana Developer Console 创建一个新的OAuth应用。
- 在应用设置中，设置重定向URI。对于本地开发，通常是 'http://localhost:3000/oauth/callback'。如果你将部署到云端，则需要使用你的应用对应的生产环境URL（例如 'https://your-app.railway.app/oauth/callback'）。
- 配置 'default' 或所需范围的权限（建议选择 'default' 以获得完整功能）。
- 保存生成的 'CLIENT_ID' 和 'CLIENT_SECRET'。
配置环境变量:
- 复制 '.env.example' 文件到 '.env' 文件：
```
cp .env.example .env
```
- 编辑新创建的 '.env' 文件，填入你在上一步骤中获得的 'ASANA_CLIENT_ID' 和 'ASANA_CLIENT_SECRET'，以及你在Asana应用中注册的 'ASANA_REDIRECT_URI'。
启动服务器:
```
python -m src.server_http
```
服务器将启动并在 'http://localhost:3000' 监听请求。

服务器配置 (供MCP客户端连接)

MCP客户端（如Claude Code）需要通过JSON配置来连接到此服务器。以下是一个配置示例，展示了如何设置连接到该MCP服务器的参数。请根据你的实际部署地址修改 'url'。

{
  "server_name": "Asana MCP Railway",
  "description": "连接到Asana工作管理平台的MCP服务器，提供任务、项目、部门等42项功能，支持多用户OAuth认证。部署在Railway或本地。",
  "command": "python",
  "args": [
    "-m",
    "src.server_http"
  ],
  "env": {
    "ASANA_CLIENT_ID": "YOUR_ASANA_CLIENT_ID",
    "ASANA_CLIENT_SECRET": "YOUR_ASANA_CLIENT_SECRET",
    "ASANA_REDIRECT_URI": "YOUR_SERVER_REDIRECT_URI",
    "PORT": "3000",
    "HOST": "0.0.0.0"
  },
  "transport": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  },
  "authentication": {
    "type": "oauth2",
    "oauth_url": "http://localhost:3000/oauth/start",
    "status_url": "http://localhost:3000/oauth/status"
  },
  "scopes": ["user"]
}

配置参数注释：

'server_name': 服务器的显示名称，用于在MCP客户端中标识。
'description': 服务器功能的详细描述，帮助用户理解其用途。
'command': 启动服务器的Python解释器路径（例如，'python' 或 '/usr/bin/python3'）。
'args': 启动服务器所需的Python模块参数。
'env': 服务器运行所需的Asana OAuth环境变量，你需要将 'YOUR_ASANA_CLIENT_ID'、'YOUR_ASANA_CLIENT_SECRET' 和 'YOUR_SERVER_REDIRECT_URI' 替换为你的实际值。
- 'ASANA_CLIENT_ID': 在Asana开发者控制台注册应用后获得的客户端ID。
- 'ASANA_CLIENT_SECRET': 在Asana开发者控制台注册应用后获得的客户端密钥。
- 'ASANA_REDIRECT_URI': Asana OAuth回调地址，必须与在Asana应用中注册的地址完全一致。
- 'PORT': 服务器监听的端口号（默认为3000）。
- 'HOST': 服务器监听的IP地址（默认为0.0.0.0，表示监听所有可用网络接口）。
'transport': 定义MCP客户端与服务器通信所使用的协议和地址。
- 'type': 使用 'http' 作为传输类型。
- 'url': MCP服务器的入口URL。如果服务器在本地运行，通常是 'http://localhost:3000/mcp'；如果部署到Railway或其他云平台，则应替换为你的应用实际的公共 'https' URL，例如 'https://your-app.railway.app/mcp'。
'authentication': 定义用户身份验证的方式。
- 'type': 使用 'oauth2' 认证流程。
- 'oauth_url': 启动OAuth认证流程的URL，用户需要访问此URL来授权。
- 'status_url': 查询当前认证状态的URL。
'scopes': LLM客户端访问此服务器所需的范围，'user' 表示此服务器为用户级资源。

基本使用方法

进行认证: 在启动服务器后，打开浏览器访问 'http://localhost:3000/oauth/start' (如果你部署在云端，则访问你应用的公共URL)。完成Asana的授权流程。授权成功后，你将看到一个成功消息页面。
在LLM客户端中添加MCP服务器 (以Claude Code为例): 在你的LLM客户端（如Claude Code）的终端中，执行以下命令添加MCP服务器：
```
claude mcp add --transport http --scope user asana http://localhost:3000/mcp
```
请将 'http://localhost:3000' 替换为你的MCP服务器的实际访问地址。
测试功能: 现在你可以向你的LLM客户端提问，让它调用Asana MCP服务器提供的工具来管理Asana任务和项目，例如：
- "List my Asana workspaces" (列出我的Asana工作区)
- "Search for incomplete tasks in workspace [你的工作区GID]" (在指定工作区中搜索未完成的任务)
- "Create a task named 'Test MCP' in project [你的项目GID]" (在指定项目中创建一个名为'Test MCP'的任务) LLM客户端还会利用内置的 'asana-mcp-field-guide' 技能，为你提供Asana API使用的最佳实践和优化建议。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (供MCP客户端连接)

基本使用方法

信息