@agllama/mcp

Connect your AI client to AG-Llama project management using the Model Context Protocol (MCP). Manage issues, sprints, and boards directly from Claude Code, Claude Desktop, Codex CLI, Cursor, Gemini CLI, or VS Code/Copilot.

Not affiliated with LlamaIndex, LlamaCloud, or Meta's Llama models. "AG-Llama" is an independent agile project-management tool. Published and maintained by Keith Willis ([email protected]); source at github.com/WillisK-0/J-Killer under packages/mcp-server.

Supply-chain verification: Releases are published from GitHub Actions with npm provenance. Each version on npm shows a "Built and signed on GitHub Actions" attestation linking back to the exact commit and workflow that produced it — so a stolen npm token alone cannot publish a counterfeit. Verify locally with npm audit signatures. Full details, including maintainer-identity history and vulnerability reporting, are in SECURITY.md.

What is AG-Llama?

AG-Llama is a modern, lightweight Jira alternative for agile teams. This MCP server lets your AI client interact with your projects, create issues, manage sprints, and automate workflows without leaving your conversation.

Installation

No installation required! Run directly with npx:

npx @agllama/mcp

Quick Start

1. Get Your API Key

1. Sign up at agllama.onrender.com
2. Navigate to Profile → MCP Integration
3. Click "Generate API key"
4. Copy the key (shown only once)

2. Configure your MCP client

AG-Llama is MCP-native — pick your client below. Six clients work today: Claude Code, Claude Desktop, Codex CLI, Cursor, Gemini CLI, and VS Code/Copilot. Every client but VS Code uses an mcpServers JSON block; VS Code uses servers (no mcpServers fallback); Codex CLI uses TOML. The Claude config stays byte-identical to past versions; the other sections are additive.

Config formats verified 2026-05-24:

• Cursor: https://cursor.com/docs/context/mcp
• Codex: https://developers.openai.com/codex/mcp

For Claude Desktop App

Edit your Claude Desktop config file:

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

Add this configuration:

{
  "mcpServers": {
    "llama": {
      "command": "npx",
      "args": ["-y", "@agllama/mcp"],
      "env": {
        "LLAMA_API_URL": "https://api.ag-llama.com",
        "LLAMA_API_KEY": "llm_xxxxxxxx"
      }
    }
  }
}

Replace llm_xxxxxxxx with your actual API key.

Windows users: Replace "command": "npx" with "command": "cmd" and prepend "/c", "npx" to the args array:

"command": "cmd",
"args": ["/c", "npx", "-y", "@agllama/mcp"]

For Claude Code (CLI)

If you're using Claude Code, add to your project's .mcp.json:

{
  "mcpServers": {
    "llama": {
      "command": "npx",
      "args": ["-y", "@agllama/mcp"],
      "env": {
        "LLAMA_API_URL": "https://api.ag-llama.com",
        "LLAMA_API_KEY": "llm_xxxxxxxx"
      }
    }
  }
}

Or use the Claude CLI:

claude mcp add llama -- npx -y @agllama/mcp

Then set environment variables:

export LLAMA_API_URL=https://api.ag-llama.com
export LLAMA_API_KEY=llm_xxxxxxxx

For Codex CLI

Edit ~/.codex/config.toml (user-wide) or .codex/config.toml (trusted project):

[mcp_servers.llama]
command = "npx"
args = ["-y", "@agllama/mcp"]

[mcp_servers.llama.env]
LLAMA_API_URL = "https://api.ag-llama.com"
LLAMA_API_KEY = "llm_xxxxxxxx"

For Cursor

Edit ~/.cursor/mcp.json (user-wide) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "llama": {
      "command": "npx",
      "args": ["-y", "@agllama/mcp"],
      "env": {
        "LLAMA_API_URL": "https://api.ag-llama.com",
        "LLAMA_API_KEY": "llm_xxxxxxxx"
      }
    }
  }
}

For Gemini CLI

Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "llama": {
      "command": "npx",
      "args": ["-y", "@agllama/mcp"],
      "env": {
        "LLAMA_API_URL": "https://api.ag-llama.com",
        "LLAMA_API_KEY": "llm_xxxxxxxx"
      }
    }
  }
}

For VS Code / GitHub Copilot

Edit .vscode/mcp.json in your project (or run the Command Palette action MCP: Open User Configuration for a user-wide config). VS Code's top-level key is servers, not mcpServers — there is no mcpServers fallback, so pasting a Claude-style config here fails silently. Requires VS Code 1.102 or later, the release where MCP support went GA and the servers key became supported.

{
  "servers": {
    "llama": {
      "command": "npx",
      "args": ["-y", "@agllama/mcp"],
      "env": {
        "LLAMA_API_URL": "https://api.ag-llama.com",
        "LLAMA_API_KEY": "llm_xxxxxxxx"
      }
    }
  }
}

For any other MCP client (Generic)

Any MCP client that supports stdio transport can connect with the raw command and env vars:

npx -y @agllama/mcp

# Environment:
LLAMA_API_URL=https://api.ag-llama.com
LLAMA_API_KEY=llm_xxxxxxxx

ChatGPT isn't supported yet

ChatGPT can only reach MCP servers over HTTPS from OpenAI's own servers — it can't spawn a local npx process the way the clients above do. Connecting it would require a hosted connector, which AG-Llama doesn't offer yet.

3. Restart your client

Restart Claude Desktop, Claude Code, or whichever client you configured to load the MCP server.

4. Test the Connection

In your AI client, try:

Use llama to test the connection

You should see your user info and available organizations.

Usage Examples

Get Project Overview

Use llama to get the context for my-team/PROJ

Your AI client will show you the active sprint, backlog, workflow statuses, and team members.

Create Issues

Use llama to create a high-priority story in my-team/PROJ:
- Summary: "Add user authentication"
- Description: "Implement JWT-based auth with refresh tokens"

Manage Sprints

Use llama to:
1. Show me the backlog for my-team/PROJ
2. Create a new sprint called "Sprint 5"
3. Add the top 3 highest-priority issues to it
4. Start the sprint

Search Issues

Use llama to find all critical bugs assigned to me in my-team

Board Operations

Use llama to show me the board for my-team/PROJ

Automate Workflows

Use llama to suggest a workflow for "sprint planning"

Your AI client will find and execute saved workflows from your organization.

Available Tools

The MCP server provides 40+ tools organized into categories:

Core Operations

• Context & Connection: Test connection, get project snapshots
• Organizations: List, create, and manage orgs
• Projects: Create and configure projects
• Issues: Full CRUD operations, status transitions, assignments
• Sprints: Create, start, complete sprints, manage sprint backlog
• Boards: View kanban boards, move issues between columns

Collaboration

• Comments: Add, update, delete comments on issues
• Issue Links: Create relationships (blocks, relates to, duplicates)
• Labels: Create and manage issue labels
• Members: List team members

Automation

• Search: Find issues with filters
• Workflows: Create and run reusable workflows
• Help: Built-in documentation (llama_help)

See MCP_TOOLS.md for the full tool reference.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | LLAMA_API_URL | Yes | API endpoint (production: https://api.ag-llama.com) | | LLAMA_API_KEY | Yes | Your API key from AG-Llama Profile → MCP Integration |

Self-Hosted Setup

Running your own AG-Llama instance? Configure the MCP server with your local or custom API URL:

{
  "mcpServers": {
    "llama": {
      "command": "npx",
      "args": ["-y", "@agllama/mcp"],
      "env": {
        "LLAMA_API_URL": "http://localhost:3001",
        "LLAMA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Troubleshooting

Windows: "spawn npx ENOENT" or tools not loading

• On Windows, npx must be invoked through cmd. Use "command": "cmd" with "args": ["/c", "npx", "-y", "@agllama/mcp"]

"Connection failed" error

• Verify your API key is correct
• Check that LLAMA_API_URL is set to https://api.ag-llama.com
• Ensure you've restarted your client after configuration changes

"Invalid API key" error

• Generate a new API key at agllama.onrender.com/profile → MCP Integration
• Make sure the key starts with llm_

Tools not showing up

• Confirm the MCP server is configured correctly in your client's config
• Check your client's MCP server logs for errors
• Try running npx @agllama/mcp directly to test

Rate limiting

The production API has rate limits. If you're hitting limits, consider:

• Batching operations
• Using project context (llama_context) to cache information
• Self-hosting AG-Llama for unlimited access

Links

• Web App: agllama.onrender.com
• API Documentation: api.ag-llama.com
• Full Tool Reference: MCP_TOOLS.md

License

MIT License - see LICENSE file for details.

Support

• Questions: Use the llama_help tool in your AI client for built-in documentation

Built with the Model Context Protocol by Anthropic.