npm package: @projora/mcp-server
Description: MCP server for Projora task management - integrate with Claude Code and OpenCode to manage tasks, update statuses, and track work
Author: Projora
Latest version: 1.5.1

# @projora/mcp-server

A Model Context Protocol (MCP) server for [Projora](https://projora.app) task management. Integrates with Claude Code and OpenCode to manage tasks directly from your AI coding assistant.

## Features

### Task Management
- **create_task** - Create a new task in a project with optional fields (priority, assignee, due date, etc.)
- **start_task** - Start working on a task (sets status to "In Progress", adds comment, returns full context)
- **complete_task** - Mark a task as done with optional summary and automatic time logging
- **get_task** - Get detailed task information including comments, sub-tasks, and dependencies
- **update_task** - Update task fields (title, description, priority, assignee, due date, estimate)
- **update_task_status** - Update task status
- **link_branch** - Link a git branch or pull request to a task

### Time Tracking
- **log_time** - Log time worked on a task with optional description
- **add_comment** - Add a comment to a task

### Queries & Search
- **list_projects** - List all projects with task counts
- **list_tasks** - List tasks with optional filters (project, status, priority, assignee)
- **my_tasks** - Get tasks assigned to you
- **overdue_tasks** - Get all overdue tasks
- **search_tasks** - Search for tasks and projects by keyword

### Configuration & Stats
- **get_project** - Get project details including linked GitHub repository
- **get_config** - Get available statuses, priorities, and task types
- **dashboard_stats** - Get dashboard statistics overview

## Installation

```bash
npm install -g @projora/mcp-server
```

Or run directly with npx (no installation needed):

```bash
npx projora-mcp-server setup
```

## Quick Setup

### For Claude Code (Recommended)

Run this single command (replace `YOUR_TOKEN` with your API token):

```bash
claude mcp add projora \
  --env PROJORA_AUTH_TOKEN="YOUR_TOKEN" \
  -- npx -y projora-mcp-server
```

Get your API token from [Projora Settings](https://projora.app/settings/integrations).

### For OpenCode

Run the setup wizard:

```bash
npx projora-mcp-server setup
```

The wizard will prompt for your API token and automatically configure OpenCode.

### Manual Configuration

If you prefer to manually configure, see below:

<details>
<summary>Claude Code Manual Setup</summary>

Add to your `~/.claude.json`:

```json
{
  "projora": {
    "command": "npx",
    "args": ["-y", "@projora/mcp-server"],
    "env": {
      "PROJORA_AUTH_TOKEN": "your-api-token"
    }
  }
}
```
</details>

<details>
<summary>OpenCode Manual Setup</summary>

Add to your `opencode.json`:

```json
{
  "mcp": {
    "projora": {
      "type": "local",
      "command": ["npx", "-y", "@projora/mcp-server"],
      "enabled": true,
      "environment": {
        "PROJORA_AUTH_TOKEN": "your-api-token"
      }
    }
  }
}
```
</details>

### Environment Variables

- `PROJORA_AUTH_TOKEN` - Your API token (required)
- `PROJORA_GRAPHQL_URL` - GraphQL endpoint (defaults to `https://api.projora.app/graphql`, only set for self-hosted)

## Example Prompts

Once configured, use prompts like:

- "Create a task in project PROJ: Fix authentication bug"
- "Start working on task PRJ-123"
- "Show me my tasks"
- "What are the overdue tasks?"
- "Search for tasks related to authentication"
- "Mark task PRJ-123 as done with summary: Fixed the login bug"
- "Add a comment to PRJ-123: Need to review the test coverage"
- "Log 2 hours on task PRJ-123"
- "Link branch feature/auth-fix to task PRJ-123"

## Workflow Example

1. **Start a task**: "Use projora to start working on task PRJ-123"
   - Status automatically changes to "In Progress"
   - A comment is added noting work has started
   - You get the full task context including description, GitHub repo, and suggested branch name

2. **Work on the task**: Make your changes, commit code, etc.

3. **Complete the task**: "Use projora to complete task PRJ-123 with summary: Implemented the new feature with tests"
   - Status changes to "Done"
   - A completion comment is added with your summary

## Development

```bash
# Clone the repo
git clone https://github.com/projora/projora.git
cd projora/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
PROJORA_GRAPHQL_URL=http://localhost:8000/graphql PROJORA_AUTH_TOKEN=your-token npm start
```

## License

MIT

## Links

- [Projora](https://projora.app)
- [Documentation](https://projora.app/docs)
- [GitHub](https://github.com/projora/projora)