> ## Documentation Index
> Fetch the complete documentation index at: https://jira.xaviercollantes.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Windsurf

> Configure Windsurf to use Jira MCP

Set up Jira MCP in Windsurf to manage Jira tickets directly from your IDE using natural language with Cascade AI.

## Prerequisites

* Windsurf editor installed
* Jira MCP installed (see [Quickstart](/quickstart))
* jira-cli configured and authenticated

## Configuration

<Steps>
  <Step title="Open MCP settings">
    In Windsurf, go to **Settings > MCP** or open the command palette and search for "MCP".
  </Step>

  <Step title="Add Jira MCP server">
    Add the following configuration to your MCP servers:

    <Tabs>
      <Tab title="Binary installation">
        ```json theme={null}
        {
          "mcpServers": {
            "jira": {
              "command": "/usr/local/bin/jira-mcp",
              "env": {
                "JIRA_API_TOKEN": "your-api-token",
                "JIRA_AUTH_TYPE": "basic"
              }
            }
          }
        }
        ```

        <Note>
          Replace `/usr/local/bin/jira-mcp` with the actual path to your jira-mcp binary.
        </Note>
      </Tab>

      <Tab title="Development setup (uv)">
        ```json theme={null}
        {
          "mcpServers": {
            "jira": {
              "command": "uv",
              "args": ["--directory", "/ABSOLUTE/PATH/TO/jira-mcp", "run", "python", "-m", "src.main"],
              "env": {
                "JIRA_API_TOKEN": "your-api-token",
                "JIRA_AUTH_TYPE": "basic"
              }
            }
          }
        }
        ```

        <Note>
          Replace `/ABSOLUTE/PATH/TO/jira-mcp` with the actual path to your cloned repository.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Restart Windsurf">
    Restart Windsurf or reload the window to apply the changes.
  </Step>
</Steps>

## Usage examples

Once configured, you can interact with Jira using natural language in Windsurf's Cascade AI:

* "Show me my assigned tickets"
* "Create a bug ticket for the login page issue"
* "Move PROJ-123 to In Progress"
* "Add a comment to PROJ-456 explaining the fix"
* "What tickets are in the current sprint?"

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server not connecting">
    1. Verify the path to your jira-mcp binary is correct.
    2. Make sure jira-cli is properly configured by running `jira issue list` in your terminal.
    3. Check Windsurf's MCP logs for error messages.
  </Accordion>

  <Accordion title="Authentication errors">
    Ensure your Jira credentials are set in the MCP configuration's `env` field:

    ```json theme={null}
    {
      "mcpServers": {
        "jira": {
          "command": "/usr/local/bin/jira-mcp",
          "env": {
            "JIRA_API_TOKEN": "your-api-token",
            "JIRA_AUTH_TYPE": "basic"
          }
        }
      }
    }
    ```

    <Note>
      GUI applications like Windsurf do not inherit shell environment variables from `.bashrc` or `.zshrc`. Using the `env` field in the MCP configuration is the recommended approach.
    </Note>
  </Accordion>
</AccordionGroup>