Content
# MCP ↔ Asana Context-Linker
A lightweight FastAPI service that lets you push “contexts” from your Model Context Protocol (MCP) server into Asana tasks as comments.
It handles Asana OAuth, token persistence & refresh, fetching named contexts from MCP, and posting them to Asana via its Stories API.
---
## 🛠 Features
- **OAuth 2.0** flow with Asana
- **Automatic token persistence & refresh** (no manual re-auth)
- **`/asana/attach-context`** endpoint to:
1. Load a valid Asana access token
2. Fetch a named context from your MCP server
3. Post it to an Asana task as a comment
- **Health check** endpoint
- **Graceful error handling** & structured logging
- **Unit & integration tests** for token refresh, MCP fetch, and Asana post
---
## 📁 Project Layout
mcp-asana-integration/
├── backend/
│ ├── src/
│ │ ├── main.py # FastAPI app & routes
│ │ ├── config.py # Pydantic Settings
│ │ ├── logging.py # Logger setup
│ │ ├── mcp_client.py # MCPClient.fetch_context()
│ │ ├── asana/
│ │ │ ├── oauth.py # code↔token & refresh logic
│ │ │ ├── schemas.py # Pydantic models (AttachContextRequest, etc.)
│ │ │ ├── token_store.py # save/load/refresh tokens
│ │ │ └── init.py
│ ├── .env.example # TEMPLATE env vars
│ ├── Dockerfile # Containerize the service
│ └── requirements.txt
├── tests/
│ ├── test_oauth.py # refresh/token-exchange tests
│ ├── test_token_store.py # expired→refresh tests
│ └── test_attach_context.py # integration tests (MCP & Asana mocks)
├── docs/
│ └── asana-app-setup.md # Asana OAuth & webhook registration
├── .gitignore
├── README.md # ← you are here
└── docker-compose.yml # optional: local Redis/Postgres
yaml
Copy
Edit
---
## 🔧 Prerequisites
- **Python 3.10+**
- **Asana developer account** (Client ID & Secret)
- **HTTPS-accessible host** (e.g. via `ngrok` for local dev)
- **MCP server** exposing `GET /contexts/{name}` → `{ "context_text": "..." }`
---
## 🚀 Getting Started
1. **Clone & install dependencies**
```bash
git clone git@github.com:you/mcp-asana-integration.git
cd mcp-asana-integration/backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Configure environment
bash
Copy
Edit
cp .env.example .env
Populate .env with:
ini
Copy
Edit
MCP_SERVER_URL=https://your-mcp.example.com
ASANA_CLIENT_ID=<your-asana-client-id>
ASANA_CLIENT_SECRET=<your-asana-client-secret>
ASANA_REDIRECT_URI=https://your-domain.com/asana/oauth/callback
Run the service
bash
Copy
Edit
uvicorn src.main:app --reload --host 0.0.0.0 --port 3000
Expose to the internet (for Asana) via:
bash
Copy
Edit
ngrok http 3000
Register your Asana App
Follow docs/asana-app-setup.md to:
Register OAuth redirect URI
(Optional) Configure webhooks if you want event-driven behavior
Authorize & test
Visit:
php-template
Copy
Edit
https://app.asana.com/-/oauth_authorize?
client_id=<YOUR_CLIENT_ID>&
redirect_uri=<YOUR_REDIRECT_URI>&
response_type=code
After granting access, Asana redirects to /asana/oauth/callback?code=… and you’ll see your tokens.
Call the attach endpoint:
bash
Copy
Edit
curl -X POST https://your-domain.com/asana/attach-context \
-H "Content-Type: application/json" \
-d '{
"task_gid": "1234567890",
"context_name": "design_notes"
}'
A comment with your MCP context should appear on the specified Asana task.
✅ Testing
Unit tests:
bash
Copy
Edit
pytest tests/test_oauth.py tests/test_token_store.py
Integration tests (mocks MCP & Asana):
bash
Copy
Edit
pytest tests/test_attach_context.py
📦 Deployment
Build & run via Docker:
bash
Copy
Edit
docker build -t mcp-asana-integration .
docker run -d \
-e MCP_SERVER_URL=… \
-e ASANA_CLIENT_ID=… \
-e ASANA_CLIENT_SECRET=… \
-e ASANA_REDIRECT_URI=… \
-p 3000:3000 \
mcp-asana-integration
Or use docker-compose up if you need auxiliary services.
📖 Further Improvements
Add Asana webhook receiver to auto-attach contexts on specific task events
Support custom fields (instead of comments) for richer UI
Rate-limit & retry logic for MCP and Asana API calls
Deploy in Kubernetes with health-checks & auto-scaling
Publish as a public Asana Marketplace App
Connection Info
You Might Also Like
everything-claude-code
Complete Claude Code configuration collection - agents, skills, hooks,...
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
servers
Model Context Protocol Servers
servers
Model Context Protocol Servers
Time
A Model Context Protocol server for time and timezone conversions.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.