mcpconcierge/mcp-server-asana

MCP Server

This project is an MCP (Model Context Protocol) Server for the given OpenAPI URL - https://api.apis.guru/v2/specs/asana.com/1.0/openapi.json, auto-generated using AG2's MCP builder.

Prerequisites

• Python 3.9+
• pip and uv

Installation

1. Clone the repository:

   git clone <repository-url>
   cd mcp-server-asana
   uv venv .venv
   .venv\Scripts\activate
   

2. Install dependencies:

   uv pip install --editable "."
   

3. Run Server in SSE

python mcp_server/main.py sse
or
python mcp_server/main.py streamable-http

Test MCP Server with MCP Inspector

npx @modelcontextprotocol/inspector

Development

This project uses ruff for linting and formatting, mypy for static type checking, and pytest for testing.

The script handles installing dependencies using pip install -e ".[dev]". If you are not using the dev container, you can run this command manually. sh pip install -e ".[dev]" Alternatively, you can use uv: sh uv pip install --editable ".[dev]"

Linting and Formatting

To check for linting issues:

ruff check

To format the code:

ruff format

These commands are also available via the script.

Static Analysis

To run static analysis (mypy, bandit, semgrep):

./scripts/static-analysis.sh

This script is also configured as a pre-commit hook in .

Running Tests

To run tests with coverage:

./scripts/test.sh

This will run pytest and generate a coverage report. For a combined report and cleanup, you can use:

./scripts/test-cov.sh

Pre-commit Hooks

This project uses pre-commit hooks defined in . To install the hooks:

pre-commit install

The hooks will run automatically before each commit.

Running the Server

The MCP server can be started using the script. It supports different transport modes (e.g., stdio, sse, streamable-http).

To start the server (e.g., in stdio mode):

python mcp_server/main.py stdio

The server can be configured using environment variables:

• CONFIG_PATH: Path to a JSON configuration file (e.g., ).
• CONFIG: A JSON string containing the configuration.
• SECURITY: Environment variables for security parameters (e.g., API keys).

Refer to the if __name__ == "__main__": block in for details on how these are loaded.

Local configuration (tokens & defaults)

To persist your Asana token and default options, copy to mcp_server/local_settings.json and replace ASANA_PAT_PLACEHOLDER with your Personal Access Token. The file is ignored by git, and on startup the server will automatically load any values defined there.

Supported keys inside the JSON file:

• config_path: relative or absolute path to a config file such as mcp_config.json.
• security: object that matches the SECURITY JSON payload (e.g., bearer token details).
• env: optional map of additional environment variables to set when launching the server.
• security_path, config, mcp_settings: optional values for referencing additional JSON content.

If you keep the file elsewhere, point the loader at it by exporting MCP_LOCAL_SETTINGS with the desired path once.\r\n\r\nAlternatively, you can skip the JSON file when deploying (e.g., on Coolify) by setting an ASANA_PAT environment variable with your Personal Access Token. The server will wrap it in the correct bearer configuration automatically at startup.\r\n\r\nFor hosting scenarios, set MCP_HOST and MCP_PORT environment variables to choose the bind address and port (e.g., 0.0.0.0 and 3000) without crafting a JSON MCP_SETTINGS value.\r\n\r\nThe server exposes two custom tools expected by ChatGPT connectors: search (typeahead-based lookup for tasks/projects) and fetch (retrieve full details by task:<gid> or project:<gid>). Optionally set ASANA_WORKSPACE_GID to pin searches to a specific workspace, and ASANA_SEARCH_LIMIT to cap the number of results returned.\r\n\r\n### Protecting the endpoint\r\n\r\nSet MCP_API_KEY to require every request to include either an X-MCP-API-Key header or an Authorization: Bearer token that matches the shared secret. Optional helpers:\r\n* MCP_API_KEY_HEADER - override the header name if you prefer something else.\r\n* MCP_API_KEY_EXEMPT - comma separated list of paths that should remain publicly accessible (leave empty to secure everything).\r\n\r\nShare the API key inside your company and provide it in the connector configuration so only trusted clients can reach the server.

The file demonstrates how to start and interact with the server programmatically for testing.

Building and Publishing

This project uses Hatch for building and publishing. To build the project:

hatch build

To publish the project:

hatch publish

These commands are also available via the script.