AI导哈

Asana MCP服务器

生产就绪的Asana模型上下文协议（MCP）服务器，提供OAuth 2.0认证和42种全面的任务和项目管理工具。

  • by MagicTurtle-s
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 MagicTurtle-s/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
  4. 配置作用域： default （或特定范围）
  5. 保存 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

  2. 创建铁路项目

  3. 配置环境变量

    在铁路仪表板中，添加：

    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

  4. 部署

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

  5. 更新Asana OAuth应用程序

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

  6. 测试部署

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

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

  7. 在Claude代码中配置

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

配置

环境变量

变量 必填 描述
ASANA_CLIENT_ID 是 OAuth应用程序客户端ID
ASANA_CLIENT_SECRET 是 OAuth应用程序客户端密钥
ASANA_REDIRECT_URI 是 OAuth回调URL
PORT 无 服务器端口（默认值：3000）
HOST 否 服务器主机（默认值：0.0.0.0）
NODE_ENV 否 环境（开发/生产）
LOG_LEVEL 否 日志记录级别（默认值：info）

速率限制

  • 免费计划：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美元/月

支持

相关项目

  • 克劳德码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

相关 MCP