Astravue MCP Server

Astravue MCP Server

The Astravue MCP Server is a cloud-based bridge between your Astravue workspace and compatible AI tools. Once configured, it enables those tools to interact with your spaces, projects, tasks, time entries, and custom fields in real time. All actions are authenticated via OAuth 2.0 and respect the user's existing access controls.

With the Astravue MCP Server, you can:

• Search and browse spaces, projects, and tasks without switching tools.
• Create and update tasks, subtasks, checklists, and comments through natural language.
• Track time with live timers or manual entries and generate timesheet reports.
• Manage custom fields including dropdowns, dates, currencies, and more.
• Automate workflows like sprint planning, status reporting, and bulk task updates.

It's designed for project managers, developers, and teams who use AI-powered IDEs or assistants and want to manage work without context switching.

Supported Clients

All clients connect to the same endpoint: https://api.astravue.com/mcpYou will be asked to sign in to Astravue in your browser the first time you connect.

Setup Instructions

Claude Code

Run the following command in your terminal:

claude mcp add --transport http astravue-mcp https://api.astravue.com/mcp

Your browser will open automatically. Sign in with your Astravue account and click Approve.

To confirm the connection, run /mcp in a new Claude Code session. You should see astravue-mcp listed with a green connected status.

Add the --scope project flag to create a .mcp.json file in your project root:

claude mcp add --transport http --scope project astravue-mcp https://api.astravue.com/mcp

Commit .mcp.json to your repository so teammates automatically get the connection.

Claude Desktop

Requires a Claude Pro, Max, Team, or Enterprise plan.

1. Go to Settings → Connectors in Claude Desktop.
2. Click Add custom connector and enter: https://api.astravue.com/mcp
3. Sign in with your Astravue account in the browser and click Approve.

If Connectors is not available in your Claude Desktop version, edit:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "astravue-mcp": {
      "type": "http",
      "url": "https://api.astravue.com/mcp"
    }
  }
}

Save the file and restart Claude Desktop.

Claude.ai (Web)

Requires a Claude Pro, Max, Team, or Enterprise plan.

1. Go to claude.ai → Settings → Connectors
2. Click Add connector and enter: https://api.astravue.com/mcp
3. Sign in with your Astravue account in the browser and click Approve.

Claude Mobile (iOS / Android)

Claude Mobile uses the same connector ecosystem as Claude.ai.

Add the connector on Claude.ai (web) or Claude Desktop first — it will automatically appear on your mobile app. No separate setup needed.

Cursor

1. Go to Cursor Settings → Tools & MCP
2. Click New MCP Server — this opens your mcp.json file
3. Add the following configuration:

{
  "mcpServers": {
    "astravue-mcp": {
      "url": "https://api.astravue.com/mcp"
    }
  }
}

4. Save the file. Your browser will open — sign in with your Astravue account and click Approve.

Create a .cursor/mcp.json file in your project root with the same config above. This scopes the connection to that project only.

VS Code

1. Add a .vscode/mcp.json file to your project root:

{
  "servers": {
    "astravue-mcp": {
      "type": "http",
      "url": "https://api.astravue.com/mcp"
    }
  }
}

2. Open Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run MCP: List Servers, and click Start next to astravue-mcp.
3. Authenticate with your Astravue account in the browser.

Add this to your User Settings (JSON):

{
  "mcp": {
    "servers": {
      "astravue-mcp": {
        "type": "http",
        "url": "https://api.astravue.com/mcp"
      }
    }
  }
}

Windsurf

1. Open the Windsurf MCP config file:

   • macOS / Linux: ~/.codeium/mcp_config.json
   • Windows: C:\Users\[username]\.codeium\mcp_config.json
   • Or go to Settings → Tools → Windsurf Settings → Add Server

2. Add the following:

{
  "mcpServers": {
    "astravue-mcp": {
      "serverUrl": "https://api.astravue.com/mcp"
    }
  }
}

If you already have other servers in your config, add astravue-mcp alongside them inside the existing mcpServers object — don't replace the entire file.

3. Reload Windsurf and authenticate with your Astravue account.

Cline

1. Click the Cline icon in the VS Code sidebar → click the menu (⋮) in the top right → select MCP Servers.
2. Go to the Remote Servers tab and fill in:
   • Server Name: astravue-mcp
   • Server URL: https://api.astravue.com/mcp
   • Transport Type: Streamable HTTP
3. Click Add Server. Your browser will open — sign in and click Approve.

Click Configure MCP Servers in the Configure tab to open cline_mcp_settings.json and add:

{
  "mcpServers": {
    "astravue-mcp": {
      "url": "https://api.astravue.com/mcp",
      "type": "streamableHttp"
    }
  }
}

JetBrains (IntelliJ, WebStorm, PyCharm, etc.)

1. Go to Settings → Tools → AI Assistant → Model Context Protocol (MCP)
2. Click Add → Select Streamable HTTP → Paste:

{
  "mcpServers": {
    "astravue-mcp": {
      "url": "https://api.astravue.com/mcp"
    }
  }
}

3. Click OK, then Apply. Sign in with your Astravue account in the browser.

Gemini CLI

Copy gemini-extension.json from this repository to your Gemini CLI extensions directory, or add the server URL to your Gemini MCP configuration.

Other MCP Clients

For any client that supports Streamable HTTP + OAuth 2.0:

If your client only supports SSE transport, run:

npx -y mcp-remote@latest https://api.astravue.com/mcp

Point your client to the local mcp-remote process instead of the Astravue URL.

How It Works

Astravue MCP exposes workspace operations as tools that AI assistants can call. Each tool performs a specific action in your Astravue workspace such as creating projects, managing tasks, logging time, or retrieving reports.

When an AI assistant receives a request, it selects the appropriate tool based on the user's prompt and executes it with the required parameters.

Authentication: All tools require an active authenticated session. If a tool call fails with 401 Unauthorized, reconnect your AI client to refresh your session.

Destructive actions: Some tools perform destructive actions such as deleting tasks, projects, or spaces. Most AI clients require confirmation before executing these operations. Always review actions before approving them.

Permissions

Astravue MCP respects the same role-based access control as the Astravue web app. Every tool call is executed as your authenticated user with your existing permissions. You cannot access or modify anything through MCP that you cannot access in the app.

Organization Roles

Space-Level Permissions

Project-Level Permissions

Task-Level Permissions

If a tool call returns 403 Access Denied, it means your account does not have the required role for that action. Contact your workspace admin to update your permissions.

Example Workflow

A user asks an AI assistant:

"Create a new sprint called Sprint 5 and add tasks for login, payments, and API docs."

The AI assistant may execute these tools:

1. astravue_create_project — creates the Sprint 5 project
2. astravue_bulk_create_tasks — creates the three tasks in one call
3. astravue_update_task — sets priorities or due dates as needed

This allows complex project setup to be completed from a single conversation.

Available Tools

The Astravue MCP Server provides 87 tools across the following categories.

Skills

This repository includes ready-to-use skills that automate common project management workflows:

Skills are available automatically when using the Claude Code or Cursor plugin.

Data and Security

• All traffic is encrypted via HTTPS using TLS 1.2 or later.
• OAuth 2.0 authentication ensures secure access control.
• Data access respects your workspace role and project-level permissions.
• The MCP server never stores credentials — authentication is handled per session.

For more details, see SECURITY.md.

Rate Limits

Astravue MCP enforces rate limits to ensure platform stability.

If the limit is exceeded, the server returns HTTP 429 Too Many Requests. Wait 60 seconds before retrying.

Troubleshooting

Sign out of Astravue at app.astravue.com, sign back in, then reconnect your AI client.

Your OAuth session expired. Reconnect your client to trigger a new sign-in flow.

Ensure your client supports Streamable HTTP transport. Clients that only support SSE must use the mcp-remote bridge (see Other MCP Clients).

OAuth tokens expire periodically. Your client should refresh automatically. If it does not, reconnect once.

FAQ

No. Astravue MCP works on all plans including free.

Yes. Each user authenticates with their own Astravue account.

Astravue MCP only has access to resources your account already has permission to access. All actions are performed as your authenticated user.

No. OAuth 2.0 is required so every action is tied to an authenticated user.

Most AI clients ask for confirmation before executing write operations. Check your client's tool approval settings.

Contributing

We welcome contributions. See CONTRIBUTING.md for guidelines.

Code of Conduct

This project follows the Contributor Covenant.

License

This project is licensed under the Apache License 2.0.

Copyright 2026 Astravue.

Support

• Open an issue on GitHub
• Email [email protected]
• Visit help.astravue.com