Atlassian Goals & Projects Server

An MCP server that gives AI assistants (Claude, Cursor, etc.) direct access to Atlassian Goals and Atlassian Projects via the Townsquare / Atlas GraphQL API.

Works on macOS and Windows. Each user authenticates with their own Atlassian API token.

What you can do with this MCP

Atlassian Goals

• Fetch any Atlassian Goal by key (name, owner, status)
• Read the latest goal status update including detailed notes

Atlassian Projects

• Search Atlassian Projects with optional TQL filters and pagination
• Fetch detailed project updates within a date range, including:
  • Status update summaries
  • Highlights: decisions, learnings, and risks
  • Linked Jira work items (epic/issue key, summary, status, URL)
  • Update notes

Tools

Tool	Scope	Description
get_goal	Goals	Fetch an Atlassian Goal by key (id, name, owner, archived status)
get_goal_latest_update	Goals	Latest status update + detailed notes for an Atlassian Goal
search_projects	Projects	Search Atlassian Projects with optional TQL filter and pagination
get_project_updates	Projects	Detailed updates, highlights (decisions/learnings/risks), linked Jira items for one or more Atlassian Projects in a date range

Prerequisites

• Node.js 18+ (macOS and Windows)
• A personal Atlassian API token (each user creates their own)
• Your Atlassian site's Cloud ID

Step 1: Generate your Atlassian API token

Each user needs their own token. Tokens are personal and should not be shared.

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Give it a label (e.g. "MCP Server") and click Create
4. Copy the token immediately — you will not be able to see it again

Your API token inherits the permissions of your Atlassian account. It can read any Goal or Project you have access to.

Step 2: Find your Cloud ID

Visit this URL in your browser (replace yoursite with your actual Atlassian subdomain):

https://yoursite.atlassian.net/_edge/tenant_info

The JSON response contains a cloudId field — copy that UUID value.

Step 3: Clone and build

git clone https://github.com/jaimesm-mews/atlassian-goals-projects-mcp.git
cd atlassian-goals-projects-mcp
npm install
npm run build

Step 4: Configure your MCP client

The server reads credentials from environment variables set in your MCP client config. You need four values:

Variable	Description	Example
ATLASSIAN_BASE_URL	Your Atlassian site URL	https://mews.atlassian.net
ATLASSIAN_EMAIL	Your Atlassian account email	[email protected]
ATLASSIAN_API_TOKEN	Your personal API token (from Step 1)	ATATT3x...
ATLASSIAN_CLOUD_ID	Site Cloud ID (from Step 2)	a1b2c3d4-e5f6-...

Cursor (macOS and Windows)

Add to your Cursor MCP config (.cursor/mcp.json in your project, or via Cursor Settings > MCP):

macOS:

{
  "mcpServers": {
    "atlassian-goals-projects": {
      "command": "node",
      "args": ["/Users/yourname/atlassian-goals-projects-mcp/dist/index.js"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://mews.atlassian.net",
        "ATLASSIAN_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your-token-here",
        "ATLASSIAN_CLOUD_ID": "your-cloud-id-here"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "atlassian-goals-projects": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\atlassian-goals-projects-mcp\\dist\\index.js"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://mews.atlassian.net",
        "ATLASSIAN_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your-token-here",
        "ATLASSIAN_CLOUD_ID": "your-cloud-id-here"
      }
    }
  }
}

Claude Desktop / Claude Enterprise

Add to your Claude config file:

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

{
  "mcpServers": {
    "atlassian-goals-projects": {
      "command": "node",
      "args": ["/absolute/path/to/atlassian-goals-projects-mcp/dist/index.js"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://mews.atlassian.net",
        "ATLASSIAN_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your-token-here",
        "ATLASSIAN_CLOUD_ID": "your-cloud-id-here"
      }
    }
  }
}

Windows users: use double backslashes in paths (C:\\Users\\...\\dist\\index.js) or forward slashes (C:/Users/.../dist/index.js).

Example usage

Once the MCP is connected, ask your AI assistant things like:

Goals:

• "Fetch the Atlassian Goal MEWS-3761"
• "What's the latest status update on goal MEWS-3762?"

Projects:

• "Search for all Atlassian Projects"
• "Search Atlassian Projects matching key MEWS-3866"
• "Get updates for Atlassian Projects MEWS-3866 and MEWS-4181 from 2026-03-24 to 2026-03-28"

Troubleshooting

Problem	Solution
Missing required environment variable	Check that all 4 ATLASSIAN_* env vars are set in your MCP client config
401 Unauthorized	Verify your email and API token are correct. Tokens expire if revoked at API token management
Goal X not found	Check the goal key is correct (e.g. MEWS-3761, not just 3761)
Server not appearing in Cursor/Claude	Restart the MCP client after changing config. Check the path to dist/index.js is absolute and correct for your OS

Development

npm run dev      # Run with tsx (no build step, hot reload)
npm run build    # Compile TypeScript to dist/
npm start        # Run compiled version

License

MIT