mcptix

mcptix is a ticket tracking system that integrates with AI assistants through the Model Context Protocol (MCP). You can create and manage tickets, break down complex tasks into smaller work items, store detailed planning in an agent_context field, and collaborate via comments. The MCP integration enables your AI assistant to plan, decompose, and execute work against a persistent ticket database.

How to use

You interact with mcptix through an MCP-enabled AI assistant. Start by launching the mcptix UI so you can view and manage tickets, and let your AI assistant connect to the MCP server to read, create, update, and delete tickets as needed.

Common workflows you can perform with your AI assistant include breaking down a complex feature into individual tickets, storing comprehensive planning in the agent_context field using Markdown, adding comments to tickets, and tracking ticket progress on the Kanban board.

To view and manage your tickets, open the mcptix UI. The AI assistant handles MCP interactions, while you oversee progress and adjustments.

How to install

Prerequisites and setup steps you will follow:

# Install mcptix
npm install @ownlytics/mcptix

# Initialize mcptix in your project
npx mcptix init

# Start mcptix
npx mcptix start

Additional configuration and usage notes

Configure your MCP integration so your AI assistant can start the MCP server when needed and connect to mcptix. You will typically set up a local MCP server as a stdio process that is started by your AI assistant and pointed at the mcptix MCP entry script.

When using AI assistants for planning, you store extensive planning in the agent_context field of tickets, using Markdown to organize filenames, line numbers, and method references. This allows the assistant to reference detailed plans without crowding the ticket dialogue.

Typical Kanban board columns include Backlog, Up Next, In Progress, In Review, and Completed. You can create new tickets, update existing ones, and add comments as work progresses.

Configuration examples for MCP clients

{
  "mcpServers": {
    "mcptix": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/node_modules/@ownlytics/mcptix/dist/mcp/index.js"],
      "env": {
        "MCPTIX_HOME_DIR": "/absolute/path/to/your/project/.mcptix",
        "HOME": "/home/your-username"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Troubleshooting and tips

If you encounter issues with starting the UI or connecting the MCP server, ensure all paths in your MCP configuration are absolute, the MCP server script exists at the specified location, and your AI assistant supports MCP. Check that the mcptix data directory is accessible and that Node.js is installed and up to date.

Kanban board usage details

Open mcptix to access the Kanban board with columns for Backlog, Up Next, In Progress, In Review, and Completed. Use the New Ticket button to create tickets, fill in the title, description, and priority, and save. Click a ticket to edit details, and add comments in the Comments section.

Security and data considerations

Because planning details and task descriptions may be stored in the agent_context field, ensure your MCP-enabled setup restricts access to tickets and their metadata. Use appropriate file permissions for any local storage and limit exposure of sensitive information in comments and ticket descriptions.

Advanced configuration

You can customize the mcptix experience by adjusting the API server port and host, and by choosing where you store data. For example, you can change the API port and host to suit your network setup, or point the database to a different location if needed.

Command line reference

- Initialize mcptix in your project: npx mcptix init
- Start mcptix: npx mcptix start
- Start with custom port and host: npx mcptix start --port 3001 --host 0.0.0.0
- Start without opening the browser: npx mcptix start --no-open
- Start only the MCP server (for development/testing purposes): npx mcptix mcp

Understanding the MCP architecture

The MCP server is designed to be started by your AI assistant when needed. This ensures it runs only during interactions, has access to the correct database, and is configured for your specific AI assistant.

License & Usage

This project uses a Business Source License 1.1 (BSL 1.1). You may use it for non-commercial purposes, including internal evaluation, experimentation, or research. Commercial use requires a separate license from the rights holder.