astravue-mcp

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.

Full product documentation lives at docs.astravue.com.

Astravue is a verified and reviewed integration in the Claude Connectors Directory.

---

Supported Clients

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

Client	Docs	Transport
Claude Code	MCP setup	Streamable HTTP
Claude Desktop	Connectors Directory	Streamable HTTP
Claude.ai (Web)	Connectors Directory	Streamable HTTP
Claude Mobile	Connectors Directory	Streamable HTTP
Cursor	MCP setup	Streamable HTTP
VS Code	MCP setup	Streamable HTTP
Windsurf	MCP setup	Streamable HTTP
Cline	MCP setup	Streamable HTTP
JetBrains IDEs	MCP setup	Streamable HTTP
Gemini CLI	MCP setup	Streamable HTTP

---

Setup Instructions

Claude Connectors Directory (recommended)

Astravue is available as a verified connector across Claude.ai, Claude Desktop, Claude Mobile, Claude Code, and Cowork.

1. In Claude.ai or Claude Desktop, go to Customize → Connectors.
2. Click +, browse the Connectors Directory, and search for Astravue.
3. Select Astravue, click Connect, then sign in to Astravue and approve access.
4. Start a new conversation and enable Astravue from the + → Connectors menu.

When Claude Code is authenticated with your Claude.ai subscription, the connector is available automatically. Run /mcp to confirm it is connected. Claude Code sessions using an API key, Bedrock, or Vertex do not load Claude.ai connectors; use the direct connection command below instead.

---

Claude Code

The Connectors Directory provides the verified MCP connection. For eight guided project-management workflows as well, install the Astravue plugin. A direct MCP connection remains available for API-key, Bedrock, Vertex, and custom setups.

Option A — Install as a Claude Code plugin (recommended)

The plugin bundles the MCP server with eight pre-built skills that automate common project management workflows. It is listed in Anthropic's community plugin marketplace.

Inside Claude Code, run:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install astravue@claude-community
/reload-plugins

Alternatively, install directly from this repository:

/plugin marketplace add AstravueOrg/astravue-mcp-server
/plugin install astravue@astravue
/reload-plugins

After install, run /mcp to confirm astravue is connected, then open /plugin and switch to the Installed tab to view the bundled skills.

See Anthropic's plugin discovery docs for installation scopes (user, project, local).

Option B — Install only the MCP server

If you only want the raw MCP server without the bundled skills, run:

claude mcp add --transport http astravue 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 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 https://api.astravue.com/mcp

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

---

Claude Desktop

1. Go to Customize → Connectors in Claude Desktop.
2. Click +, browse the directory, and search for Astravue.
3. Select Astravue, click Connect, then sign in and approve access.

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)

1. Go to claude.ai → Customize → Connectors.
2. Click +, browse the directory, and search for Astravue.
3. Select Astravue, click Connect, then sign in and approve access.

---

Claude Mobile (iOS / Android)

Claude Mobile uses the same connector ecosystem as Claude.ai. Connect Astravue from the mobile Connectors Directory, or connect it once on Claude.ai or Claude Desktop and use the same Claude account on mobile.

---

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:

Setting	Value
Server URL	https://api.astravue.com/mcp
Transport	Streamable HTTP
Authentication	OAuth 2.0 (Authorization Code + PKCE)

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

Role	MCP Access
Account Admin	Full access to all spaces, projects, and tasks across the organization
Admin	Full access to all spaces, projects, and tasks across the organization
Manager	Can manage spaces and projects they are a member of
Member	Can read and write within spaces and projects they belong to
Guest	Read-only. Cannot perform any write operations through MCP

Space-Level Permissions

Action	Required Role
List spaces, view space details	Space Member
Create, update, delete a space	Org Admin or Manager

Project-Level Permissions

Action	Required Role
List tasks, view project details	Project Member
Create or update tasks	Project Member
Add project members, delete project	Project Admin
Manage custom fields, statuses	Project Admin

Task-Level Permissions

Action	Required Role
View tasks, comments, checklists	Project Member
Create tasks, add comments, log time	Project Member
Delete a task	Task Owner, Task Creator, or Project Admin
Delete a comment	Comment Creator or Org Admin

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.

Tool	Description	Example Prompt
astravue_list_spaces	Lists all spaces in your organization	"Show me all my spaces"
astravue_get_space	Gets details of a specific space including its projects	"What projects are in the Design space?"
astravue_create_space	Creates a new space	"Create a space called Product Development"
astravue_update_space	Updates a space name or settings	"Rename the Marketing space to Growth"
astravue_delete_space	Permanently deletes a space and all its contents	"Delete the archived Test space"

Tool	Description	Example Prompt
astravue_list_projects	Lists all projects within a space	"List all projects in the Engineering space"
astravue_get_project	Gets full details of a specific project	"What's the current status of Sprint 3?"
astravue_create_project	Creates a new project inside a space	"Create a project called Q2 Roadmap in the Product space"
astravue_update_project	Updates a project's name, status, priority, or health	"Mark Sprint 1 as completed"
astravue_delete_project	Permanently deletes a project and all its tasks	"Delete the duplicate Onboarding project"
astravue_add_project_member	Adds an existing workspace member to a project	"Add john@company.com to the Backend project"

Tool	Description	Example Prompt
astravue_list_project_tasks	Lists all tasks within a project	"Show all open tasks in Sprint 2"
astravue_get_task	Gets full task details	"What's the status of the login bug task?"
astravue_find_tasks	Searches tasks by keyword across all projects	"Find all tasks related to payments"
astravue_create_task	Creates a task in a project	"Create a high priority task: Fix authentication bug"
astravue_update_task	Updates task fields	"Assign the API docs task to Sarah"
astravue_delete_task	Deletes a task	"Delete the duplicate checkout task"
astravue_move_task	Moves a task from one project to another	"Move the login task from Sprint 1 to Sprint 2"
astravue_duplicate_task	Creates a copy of an existing task	"Duplicate the API integration task with all subtasks"
astravue_create_personal_task	Creates a personal task not tied to any project	"Remind me to review the design doc by Friday"
astravue_bulk_create_tasks	Creates multiple tasks in one call	"Create these 10 sprint tasks with owners and priorities"
astravue_bulk_update_tasks	Updates multiple tasks at once	"Set all 5 sprint tasks to In-Progress"
astravue_bulk_delete_tasks	Deletes multiple tasks at once	"Delete all the duplicate tasks from Sprint 1"
astravue_get_task_counts	Returns task count summary: total, pending, completed, overdue	"How many tasks are open vs completed?"

Tool	Description	Example Prompt
astravue_list_subtasks	Lists subtasks under a parent task	"Show the subtasks of the authentication feature"
astravue_create_subtask	Creates a new subtask	"Add a subtask: Write unit tests under the API task"
astravue_update_subtask	Updates a subtask's title, status, or priority	"Mark the unit tests subtask as done"
astravue_delete_subtask	Deletes a subtask	"Delete the duplicate subtask under the API task"

Tool	Description	Example Prompt
astravue_get_task_comments	Lists comments on a task	"Show me all comments on the login bug task"
astravue_add_task_comment	Adds a comment to a task	"Comment on the API task: Blocked pending design review"
astravue_update_task_comment	Edits an existing comment	"Update my comment to say: Unblocked, ready for review"
astravue_delete_task_comment	Deletes a specific comment	"Delete my last comment on the API task"

Tool	Description	Example Prompt
astravue_get_task_checklists	Gets all checklist items on a task	"Show the checklist on the deployment task"
astravue_create_checklist_item	Adds a new checklist item	"Add a checklist item: Run integration tests"
astravue_update_checklist_item	Updates a checklist item's title or completion state	"Mark 'Run integration tests' as done"
astravue_delete_checklist_item	Deletes a checklist item	"Remove the 'Update changelog' item from the checklist"

Tool	Description	Example Prompt
astravue_add_dependency	Links two tasks with a blocking relationship	"Database schema must complete before API implementation"
astravue_list_dependencies	Shows all dependencies for a task	"What does the API implementation task depend on?"
astravue_remove_dependency	Removes a dependency link	"Remove the dependency between design and implementation"

Tool	Description	Example Prompt
astravue_list_tags	Lists all tags available in your organization	"What tags do we have?"
astravue_add_tag_to_task	Adds an existing tag to a task	"Tag the login task as 'urgent'"
astravue_remove_tag_from_task	Removes a tag from a task	"Remove the 'blocked' tag from the deployment task"

Tool	Description	Example Prompt
astravue_list_attachments	Lists all attachments on a task	"What files are attached to the design task?"
astravue_delete_attachment	Deletes an attachment from a task	"Remove the old mockup file from the design task"

Tool	Description	Example Prompt
astravue_start_timer	Starts a timer on a task	"Start tracking time on the API documentation task"
astravue_stop_timer	Stops the active timer	"Stop my timer"
astravue_get_active_timers	Lists running timers	"Do I have any active timers?"
astravue_log_manual_time	Logs a time entry with a specific duration	"Log 2 hours on the API documentation task"
astravue_log_time_range	Logs time with a start and end time	"Log time from 9am to 11:30am on the backend refactor"
astravue_get_task_time_entries	Lists time entries for a task	"How much time was logged on the backend refactor?"
astravue_get_project_time_entries	Lists all time entries across a project	"Show all time logged in Sprint 2"
astravue_get_project_time_summary	Gets billable vs non-billable time totals	"How many total hours were spent on the Backend project?"
astravue_get_timesheet_report	Generates a timesheet report	"Show my timesheet for this week"
astravue_delete_time_entry	Deletes a time entry	"Delete the accidental time entry from yesterday"