quire-mcp

Quire MCP Server

A Model Context Protocol (MCP) server for the Quire project management platform.

This server allows AI assistants (like Claude) to interact with your Quire projects, tasks, and data securely.

Quick Start

Prerequisites

• Node.js v22 or higher
• A Quire account
• A Quire OAuth app (see Create a Quire OAuth App)

Step 1: Create a Quire OAuth App

• Go to Quire App Management
• Click Create new app
• Set Redirect URL to: http://localhost:3000/callback
• Choose the permission scopes you need
• Copy the Development Client ID and Development Client Secret

Step 2: Configure Your MCP Client

Choose the setup that matches your MCP client:

Claude Desktop (Recommended)

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "quire": {
      "command": "npx",
      "args": ["-y", "quire-mcp"],
      "env": {
        "QUIRE_OAUTH_CLIENT_ID": "your-client-id",
        "QUIRE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code (CLI)

Add to your Claude Code MCP settings (~/.claude/mcp.json or project-level):

{
  "mcpServers": {
    "quire": {
      "command": "npx",
      "args": ["-y", "quire-mcp"],
      "env": {
        "QUIRE_OAUTH_CLIENT_ID": "your-client-id",
        "QUIRE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Cursor

In Cursor settings, add an MCP server:

{
  "mcpServers": {
    "quire": {
      "command": "npx",
      "args": ["-y", "quire-mcp"],
      "env": {
        "QUIRE_OAUTH_CLIENT_ID": "your-client-id",
        "QUIRE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Step 3: First-Time Authorization

On first use, the server will:

• Print an authorization URL to the console
• Wait for you to open that URL in your browser
• After you grant access, Quire redirects to localhost
• The server captures the tokens and caches them

Subsequent uses will automatically refresh tokens as needed.

Transport Modes

The server supports two transport modes: stdio (default) and http.

STDIO Mode (Default)

STDIO mode is the simplest setup. The MCP client spawns the server process directly and communicates via JSON-RPC over stdin/stdout.

How it works:

• MCP client spawns npx quire-mcp with environment variables
• On first tool call, if no cached token exists, the server prints an OAuth URL to stderr
• User opens URL in browser and authorizes
• Quire redirects to localhost:3000/callback where the server captures the token
• Token is cached to disk for future use

Token cache locations:

• Windows: %APPDATA%\quire-mcp\tokens.json
• macOS: ~/Library/Application Support/quire-mcp/tokens.json
• Linux: ~/.config/quire-mcp/tokens.json

HTTP Mode

HTTP mode runs an HTTP server with OAuth 2.0 endpoints. Use this when you need:

• A long-running server process
• Multiple clients connecting to the same server
• Deployment to a remote host (e.g., Cloudflare Workers, cloud VMs)

Important: In HTTP mode, the server must be running before clients can connect. Environment variables are set on the server process, not in client configs.

Running HTTP Mode Locally

Step 1: Start the server:

# Using npx
QUIRE_OAUTH_CLIENT_ID=your-client-id \
QUIRE_OAUTH_CLIENT_SECRET=your-client-secret \
MCP_TRANSPORT=http \
npx quire-mcp

# Or using pnpm (for development)
pnpm dev:http

The server will output:

[quire-mcp] HTTP server listening on 127.0.0.1:3001
[quire-mcp] OAuth metadata: http://localhost:3001/.well-known/oauth-authorization-server
[quire-mcp] MCP endpoint: http://localhost:3001/mcp

Step 2: Configure your MCP client to connect:

{
  "mcpServers": {
    "quire": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

Note: No env section is needed in the client config for HTTP mode—the OAuth credentials are on the server.

Step 3: When the MCP client connects, it will:

• Discover OAuth endpoints via /.well-known/oauth-authorization-server
• Redirect you to authorize with Quire
• Exchange tokens and establish a session

HTTP Mode Environment Variables

Variable	Required	Default	Description
MCP_TRANSPORT	Yes	stdio	Set to http to enable HTTP mode
QUIRE_OAUTH_CLIENT_ID	Yes	-	Quire OAuth Client ID
QUIRE_OAUTH_CLIENT_SECRET	Yes	-	Quire OAuth Client Secret
MCP_SERVER_HOST	No	127.0.0.1	Host to bind the HTTP server
MCP_SERVER_PORT	No	3001	Port for the HTTP server
MCP_ISSUER_URL	No	http://localhost:3001	Base URL for OAuth endpoints
QUIRE_OAUTH_REDIRECT_URI	No	http://localhost:3001/oauth/callback	Quire OAuth callback URL

Quire App Configuration for HTTP Mode: When using HTTP mode, update your Quire app's redirect URL to: http://localhost:3001/oauth/callback

Manual Token Mode

If you have a pre-obtained access token (e.g., from Postman), you can skip OAuth entirely:

{
  "mcpServers": {
    "quire": {
      "command": "npx",
      "args": ["-y", "quire-mcp"],
      "env": {
        "QUIRE_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

Note: Manually-obtained tokens will eventually expire and won't auto-refresh without OAuth credentials.

Configuration Reference

All Environment Variables

Variable	Required	Default	Description
QUIRE_OAUTH_CLIENT_ID	Yes*	-	Quire OAuth Client ID
QUIRE_OAUTH_CLIENT_SECRET	Yes*	-	Quire OAuth Client Secret
QUIRE_ACCESS_TOKEN	No	-	Manual token override (skips OAuth flow)
QUIRE_OAUTH_REDIRECT_URI	No	http://localhost:3000/callback	OAuth callback URL (stdio mode)
QUIRE_TOKEN_STORE_PATH	No	Platform default	Path to token cache file
MCP_TRANSPORT	No	stdio	Transport mode: stdio or http
MCP_SERVER_HOST	No	127.0.0.1	HTTP server bind address
MCP_SERVER_PORT	No	3001	HTTP server port
MCP_ISSUER_URL	No	http://localhost:3001	OAuth issuer URL (HTTP mode)

*Required unless QUIRE_ACCESS_TOKEN is set.

Features

Tools

The server provides 60+ tools organized by category:

Authentication

Tool	Description
quire.whoami	Get the current authenticated user's profile

Organizations

Tool	Description
quire.listOrganizations	List all accessible organizations
quire.getOrganization	Get organization details by ID or OID
quire.updateOrganization	Update organization followers

Projects

Tool	Description
quire.listProjects	List all projects, optionally filtered by organization
quire.getProject	Get project details including task counts
quire.updateProject	Update project name, description, icon, and followers
quire.exportProject	Export project tasks in JSON or CSV format

Tasks

Tool	Description
quire.listTasks	List tasks in a project (root-level or subtasks)
quire.getTask	Get task details by project+ID or OID
quire.createTask	Create a new task with optional priority, dates, assignees, tags
quire.updateTask	Update task properties
quire.deleteTask	Delete a task and its subtasks
quire.searchTasks	Search tasks in a project by keyword and filters
quire.createTaskAfter	Create a task after a specified task
quire.createTaskBefore	Create a task before a specified task
quire.searchFolderTasks	Search tasks within a folder
quire.searchOrganizationTasks	Search tasks across an entire organization

Tags

Tool	Description
quire.listTags	List all tags in a project
quire.getTag	Get tag details by OID
quire.createTag	Create a new tag with name and color
quire.updateTag	Update tag name or color
quire.deleteTag	Delete a tag

Comments

Tool	Description
quire.listTaskComments	List all comments on a task
quire.addTaskComment	Add a comment to a task
quire.updateComment	Update comment text
quire.deleteComment	Delete a comment
quire.listChatComments	List all comments in a chat channel
quire.addChatComment	Add a comment to a chat channel

Users

Tool	Description
quire.getUser	Get user details by ID, OID, or email
quire.listUsers	List all accessible users
quire.listProjectMembers	List all members of a project

Custom Statuses

Tool	Description
quire.listStatuses	List custom statuses in a project
quire.getStatus	Get status details by value
quire.createStatus	Create a custom workflow status
quire.updateStatus	Update status name or color
quire.deleteStatus	Delete a custom status

External Teams (Partners)

Tool	Description
quire.getPartner	Get external team details
quire.listPartners	List all external teams in a project

Documents

Tool	Description
quire.createDocument	Create a document in an organization or project
quire.getDocument	Get document content and metadata
quire.listDocuments	List all documents
quire.updateDocument	Update document name or content
quire.deleteDocument	Delete a document

Sublists

Tool	Description
quire.createSublist	Create a sublist
quire.getSublist	Get sublist details
quire.listSublists	List all sublists
quire.updateSublist	Update sublist name or description
quire.deleteSublist	Delete a sublist

Chat Channels

Tool	Description
quire.createChat	Create a chat channel
quire.getChat	Get chat channel details
quire.listChats	List all chat channels
quire.updateChat	Update chat name, description, or members
quire.deleteChat	Delete a chat channel

Key-Value Storage

Tool	Description
quire.getStorageValue	Get a stored value by key
quire.listStorageEntries	List storage entries by prefix
quire.putStorageValue	Store a value
quire.deleteStorageValue	Delete a stored value

Notifications

Tool	Description
quire.sendNotification	Send notification to users

Attachments

Tool	Description
quire.uploadTaskAttachment	Upload a file attachment to a task
quire.uploadCommentAttachment	Upload a file attachment to a comment

Resources

The server exposes data as MCP resources:

Static Resources

Resource URI	Description
quire://user/me	Current authenticated user's profile
quire://organizations	List of all accessible organizations
quire://projects	List of all accessible projects

Resource Templates

Resource URI	Description
quire://project/{id}	Specific project details and metadata
quire://project/{projectId}/tasks	Root tasks in a project
quire://project/{projectId}/tags	Tags defined in a project
quire://project/{projectId}/statuses	Custom statuses in a project

Prompts

The server provides guided prompts for common workflows:

Prompt	Description
quire.create-project-plan	Generate a task plan from a goal description
quire.daily-standup	Generate a daily standup summary
quire.sprint-planning	Plan a sprint from the backlog
quire.task-breakdown	Break down a complex task into subtasks
quire.weekly-summary	Generate a weekly progress report

Development

Setup

# Clone the repo
git clone https://github.com/jacob-hartmann/quire-mcp.git
cd quire-mcp

# Use the Node.js version from .nvmrc
# (macOS/Linux nvm): nvm install && nvm use
# (Windows nvm-windows): nvm install 22 && nvm use 22
nvm install
nvm use

# Install dependencies
pnpm install

# Copy .env.example and configure
cp .env.example .env
# Edit .env with your OAuth credentials

Running Locally

# Development mode (stdio, auto-reload)
pnpm dev

# Development mode (http, auto-reload)
pnpm dev:http

# Production build
pnpm build

# Production run
pnpm start        # stdio mode
pnpm start:http   # http mode

Debugging

You can use the MCP Inspector to debug the server:

# Run from source
pnpm inspect

# Run from built output
pnpm inspect:dist

pnpm inspect loads .env automatically via dotenv (see .env.example).

If you see Ignored build scripts: esbuild..., run pnpm approve-builds and allow esbuild. In CI we install dependencies with lifecycle scripts disabled (pnpm install --ignore-scripts) and then explicitly rebuild only esbuild for the production build job.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on how to contribute to this project.

Security

See SECURITY.md for security policy and reporting vulnerabilities.

Support

This is a community project provided "as is" with no guaranteed support. See SUPPORT.md for details.

License

MIT © Jacob Hartmann