Asana MCP Railway

Asana MCP铁路服务器

Asana的生产就绪模型上下文协议（MCP）服务器 完全对等 向官方Asana MCP报告。具有OAuth 2.0身份验证和42个全面的工具，用于完成任务和项目管理。

特性

• ✅ OAuth 2.0身份验证 使用PKCE增强安全性
• ✅ 42 MCP工具 -与官方Asana MCP完全对等
• ✅ HTTP/SSE传输 用于从Claude Code进行远程访问
• ✅ 速率限制 （150-1500次请求/分钟）
• ✅ 自动令牌刷新 （1小时访问令牌生命周期）
• ✅ 多用户支持 具有每用户令牌管理
• ✅ 铁路部署 已准备好Docker配置

可用工具（共42个）

与官方Asana MCP完全对等 -支持所有必要的Asana行动。

任务管理（15个工具）

完整的任务生命周期管理，包括CRUD操作、搜索、批处理操作和子任务层次结构。

项目管理（10个工具）

完整的项目CRUD、复制、统计、部分和状态更新。

部门管理（5个工具）

完成CRUD和任务分配操作。

任务关系（8个工具）

具有完整添加/删除/查看功能的依赖关系、依赖关系和子任务关系。

任务组织（4个工具）

管理任务项目和标签（添加/删除操作）。

工作区和标签（2个工具）

工作区列表和基于标签的任务查询。

看 TOOL-LIST-v1.1.0.md 获取完整的工具文档。

📚 包含的技能

此存储库包括用于优化Asana MCP使用的Claude Code技能：

体式mcp野外指南 -执行Asana操作时自动激活的执行就绪参考。提供：

• ✅ 查询优化模式 -通过字段过滤减少30-50倍的令牌
• ✅ 日期范围最佳实践 -防止无限制的历史数据获取
• ✅ 自定义字段处理 -系统化过滤，避免响应膨胀
• ✅ 防图案指南 -常见错误和修复
• ✅ 即用型模板 -工作量检查、优先级列表、逾期分析

当您使用此MCP服务器时，技能会自动发现，并为高效使用API提供上下文感知指导。

位置: .claude/skills/asana-mcp-field-guide/SKILL.md

快速开始

1.注册Asana OAuth应用程序

1. 首选 Asana开发者控制台
2. 创建新应用
3. 设置重定向URI:

- 发展： http://localhost:3000/oauth/callback - 生产： https://your-app.railway.app/oauth/callback

1. 配置作用域： default （或特定范围）
2. 保存 CLIENT_ID 和 CLIENT_SECRET

2.地方发展

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

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env with your Asana OAuth credentials

# Start server
python -m src.server_http

服务器将在以下时间启动 http://localhost:3000

3.身份验证

1. 访问 http://localhost:3000/oauth/start
2. 完成Asana授权
3. 您将被重定向到带有成功消息的回调

4.在Claude代码中配置

# Add MCP server
claude mcp add --transport http --scope user asana http://localhost:3000/mcp

# Verify connection
claude mcp list

5.测试工具

要求Claude Code：

• “列出我的Asana工作区”
• “在工作区\[GID\]中搜索未完成的任务”
• 在项目\[GID\]中创建一个名为“测试MCP”的任务

铁路部署

先决条件

• 包含代码的GitHub存储库
• 铁路账户(railway应用程序)
• Asana OAuth应用程序配置了生产重定向URI

部署步骤

1. 连接存储库

   # Push to GitHub
   git add .
   git commit -m "Initial commit"
   git push origin main

1. 创建铁路项目

- 首选 railway应用程序 - 新项目→ 从GitHub部署 - 选择您的存储库

1. 配置环境变量

在铁路仪表板中，添加：

   ASANA_CLIENT_ID=your_client_id
   ASANA_CLIENT_SECRET=your_client_secret
   ASANA_REDIRECT_URI=https://your-app.railway.app/oauth/callback
   PORT=3000
   NODE_ENV=production

1. 部署

- Railway将使用Dockerfile自动部署 - 等待部署完成 - 注意你的应用程序URL: https://your-app.railway.app

1. 更新Asana OAuth应用程序

- 在Asana开发者控制台中添加生产重定向URI - https://your-app.railway.app/oauth/callback

1. 测试部署

   # Health check
   curl https://your-app.railway.app/health

   # Start OAuth flow
   # Visit: https://your-app.railway.app/oauth/start

1. 在Claude代码中配置

   claude mcp add --transport http --scope user asana https://your-app.railway.app/mcp

配置

环境变量

速率限制

• 免费计划：150个请求/分钟
• 高级计划：1500个请求/分钟

要使用保费率限制，请修改 src/server_http.py:

rate_limiter = RateLimiter(max_requests=1500)  # Premium tier

API终点

健康检查

GET /health

返回服务器状态和速率限制器信息。

OAuth流

GET /oauth/start

启动OAuth授权。重定向到Asana。

GET /oauth/callback?code=...&state=...

处理OAuth回调。代币的交换代码。

GET /oauth/status

检查身份验证状态。

MCP端点

POST /mcp

MCP通信端点（SSE传输）。

发展

项目结构

asana-mcp-railway/
├── src/
│   ├── __init__.py
│   ├── __main__.py
│   ├── oauth.py              # OAuth 2.0 manager
│   ├── asana_client.py       # Asana API client
│   ├── server_http.py        # HTTP server + MCP
│   ├── tools/
│   │   ├── tasks.py          # Task tools
│   │   ├── projects.py       # Project tools
│   │   ├── relationships.py  # Dependency tools
│   │   └── organization.py   # Tag/workspace tools
│   └── utils/
│       └── formatters.py     # Response formatting
├── .claude/
│   └── context.md            # Architecture docs
├── PROJECT.md                # Quick reference
├── README.md                 # This file
├── requirements.txt          # Python dependencies
├── Dockerfile                # Container config
├── railway.toml              # Railway config
└── .env.example              # Env template

运行测试

# Install dev dependencies
pip install pytest pytest-asyncio

# Run tests
pytest tests/

代码质量

# Format code
pip install black
black src/

# Type checking
pip install mypy
mypy src/

故障排除

OAuth问题

问题：“状态参数无效”

• 解决方案：清除浏览器Cookie，然后重试。状态参数将在10分钟后过期。

问题：“重定向URI不匹配”

• 解决方案：确保中的重定向URI .env 与Asana Developer Console中注册的完全匹配。

速率限制

问题：“超出费率限制”

• 解决方案：等待60秒。速率限制器会自动重试。考虑升级到Asana Premium，以获得10倍的更高限制。

令牌到期

问题：“身份验证已过期”

• 解决方案：令牌自动刷新。如果刷新失败，请通过重新验证 /oauth/start.

铁路部署

问题：健康检查失败

• 解决方案：检查铁路日志是否有错误。确保环境变量设置正确。

问题：OAuth重定向失败

• 解决方案：验证生产重定向URI是否已在Asana OAuth应用程序设置中注册。

安全考虑

令牌存储

• 发展：内存缓存（重新启动时丢失）
• 生产：建议使用Redis

- 将Redis添加到铁路项目中 - 集 REDIS_URL 环境变量 - 更新 oauth.py 使用Redis后端

HTTPS要求

• 生产OAuth需要HTTPS
• Railway默认提供HTTPS
• 开发可以使用HTTP localhost

跨域资源共享

• 目前允许所有来源(allow_origins=["*"])
• 对于生产，仅限于特定领域：

  allow_origins=["https://your-domain.com"]

性能优化

连接池

• HTTP客户端使用连接池（最多100个连接）
• 与Asana API保持连接
• 可配置 asana_client.py

缓存

考虑缓存：

• 工作区列表（很少更改）
• 项目列表（每小时刷新一次）
• 用户列表（每日刷新）

批量操作

• 使用 asana_get_multiple_tasks_by_gid 用于批量提取（最多25个）
• 比单个get_task调用更高效

成本估算

• 铁路托管：~5美元/月（爱好计划）
• API阿萨纳：免费（需要150次/分钟）
• 总计：~5美元/月

支持

• 问题:
• 文档：参见 .claude/context.md 和 PROJECT.md
• API阿萨纳: Asana开发者文档

相关项目

• 克劳德码MCP桥 -将任务从Claude Desktop委托给Claude Code
• SharePoint MCP铁路 -类似的OAuth+Railway模式
• HubSpot MCP铁路 -HTTP传输引用

许可证

麻省理工学院

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

更新日志

v0.1.0（2025-11-05）

• 初始版本
• OAuth 2.0与PKCE
• 22个MCP工具
• HTTP/SSE传输
• 铁路部署就绪

______________________________________________________________________

内置 ❤️ 通过MagicTurtle-s