keller-a16z/public-atomicwork-mcp

Atomicwork MCP Server

A Model Context Protocol (MCP) server that integrates Atomicwork with Claude Desktop and other MCP clients. This allows AI assistants like Claude to interact with your Atomicwork tickets, requests, and workflows directly.

What is Atomicwork?

Atomicwork is an enterprise service management platform that helps IT teams manage tickets, requests, changes, and incidents. This MCP server brings that functionality into your AI workflow.

Features

• 📋 List Tickets - View all tickets assigned to you
• 🔍 Search Tickets - Find tickets by keyword or criteria
• 📊 Get Ticket Details - Retrieve complete information about any ticket
• 🌐 Workspace Access - List all requests in your workspace
• 👤 Filter by User - List requests by requester email
• 💬 View Comments - Get all comments and notes on tickets

Requirements

• Node.js 18.0 or higher
• Atomicwork Account with API access
• Claude Desktop or another MCP-compatible client

Installation

Option 1: Clone and Build from Source

# Clone the repository
git clone https://github.com/keller-a16z/public-atomicwork-mcp.git
cd public-atomicwork-mcp

# Install dependencies
npm install  # or: bun install

# Build the project
npm run build  # or: bun run build

Configuration

Step 1: Get Your Atomicwork API Key

1. Log into your Atomicwork instance
2. Navigate to Settings → API (usually at https://your-company.atomicwork.com/settings/api)
3. Generate a new API key
4. Copy the key - you'll need it for configuration

Step 2: Find Your User ID and Workspace ID

Finding your User ID:

1. Open your browser's Developer Tools (F12)
2. Go to the Network tab
3. Navigate to any page in Atomicwork
4. Look for API requests to /api/v1/users/me or similar
5. Your user ID will be in the response (usually a number like 12345)

Finding your Workspace ID:

1. In the same Network tab
2. Look for API requests to /api/v1/workspaces/
3. Your workspace ID will be in the URL (usually a number like 123 or 456)

Step 3: Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "atomicwork": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/public-atomicwork-mcp/dist/index.js"
      ],
      "env": {
        "ATOMICWORK_API_KEY": "your_api_key_here",
        "ATOMICWORK_BASE_URL": "https://your-company.atomicwork.com/api/v1",
        "ATOMICWORK_USER_ID": "your_user_id",
        "ATOMICWORK_WORKSPACE_ID": "your_workspace_id"
      }
    }
  }
}

Replace:

• /ABSOLUTE/PATH/TO/public-atomicwork-mcp/dist/index.js with the actual path to the built server
• your_api_key_here with your Atomicwork API key
• your-company with your Atomicwork instance subdomain
• your_user_id with your user ID
• your_workspace_id with your workspace ID

Step 4: Restart Claude Desktop

Close and reopen Claude Desktop to load the new MCP server.

Usage

Once configured, you can interact with Atomicwork through natural language in Claude Desktop:

Example Queries

List your tickets:

Show me my current Atomicwork tickets

Get ticket details:

Get details for Atomicwork ticket ITREQ-1234

Search for tickets:

Search for tickets about "password reset"

List all workspace requests:

Show me all open requests in the workspace

Filter requests by user:

Show me all tickets from user@company.com
List requests created by john@company.com

View ticket comments:

Show me comments on ticket ITREQ-1234
Get all notes for this ticket

Available Tools

list_my_tickets

Lists all tickets assigned to you.

Parameters:

• status (optional): Filter by status (open, in_progress, resolved, closed)
• limit (optional): Maximum number of tickets to return (default: 50)

Example:

List my in-progress tickets

get_ticket_details

Gets detailed information about a specific ticket.

Parameters:

• ticket_id (required): The ID of the ticket

Example:

Show me ticket ITREQ-1234

search_tickets

Searches for tickets by keyword.

Parameters:

• query (required): Search query string
• assigned_to_me (optional): Only show tickets assigned to you (default: true)

Example:

Find tickets mentioning "GitHub"

list_all_requests

Lists all requests in the workspace (not just yours). Can filter by requester email.

Parameters:

• status (optional): Filter by status
• limit (optional): Maximum number of requests (default: 50)
• requester_email (optional): Filter by requester email address (e.g., user@company.com)

Examples:

Show all open requests in the workspace
Show me all tickets from john@company.com
List requests from jane@company.com

get_ticket_comments

Gets all comments and notes on a specific ticket.

Parameters:

• ticket_id (required): The ID or display_id of the ticket (e.g., ITREQ-1234)

Example:

Show me comments on ticket ITREQ-1234
Get all notes for ticket 567890

Troubleshooting

MCP Server Not Appearing

1. Check the configuration file path - Ensure you edited the correct claude_desktop_config.json
2. Verify the dist path - Make sure the path to dist/index.js is absolute and correct
3. Restart Claude Desktop - Changes require a full restart
4. Check logs - Look for errors in Claude Desktop's logs

API Connection Errors

"Failed to connect to Atomicwork"

• Verify your API key is correct
• Check that your base URL matches your Atomicwork instance
• Ensure you have network access to your Atomicwork instance
• Try accessing https://your-company.atomicwork.com/api/v1/users/me in your browser with the API key

"Access Token X-Api-Key is missing/invalid"

• Double-check your API key in the configuration
• Ensure the API key hasn't expired
• Try regenerating a new API key in Atomicwork

No Tickets Returned

"Error: ATOMICWORK_USER_ID not set"

• Make sure you've added your user ID to the configuration
• Verify the user ID is correct (it should be a number)

"Error: ATOMICWORK_WORKSPACE_ID not set"

• Add your workspace ID to the configuration
• Verify the workspace ID is correct (it should be a number)

Build Errors

If you're building from source and encounter errors:

# Clean and rebuild
rm -rf node_modules dist
npm install  # or: bun install
npm run build  # or: bun run build

Development

Running Locally

# Install dependencies
bun install

# Build the project
bun run build

# Test the MCP server
node dist/index.js

Project Structure

public-atomicwork-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Environment variable template
├── .gitignore           # Git ignore rules
└── README.md            # This file

Security

• Never commit your API keys - Use environment variables
• Keep your API key secure - Don't share it publicly
• Regenerate compromised keys - If your key is exposed, regenerate it immediately in Atomicwork

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Links

• Atomicwork
• Atomicwork API Documentation
• Model Context Protocol
• Claude Desktop

Support

For issues and questions:

• Bug reports: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

Inspired by the ClickUp MCP Server by taazkareem.