Skip to content

QUICKSTART.md

Latest commit

 

History

History
212 lines (159 loc) · 4.55 KB

QUICKSTART.md

File metadata and controls

212 lines (159 loc) · 4.55 KB

Quick Start Guide

Get up and running with the IBM OpenPages MCP Server in 5 minutes.

Prerequisites

  • Node.js 18 or higher
  • Access to an IBM OpenPages instance
  • Valid OpenPages credentials

Installation

  1. Clone or download this repository

    git clone <repository-url>
cd mcp-openpages-server

  2. Install dependencies

    npm install

  3. Build the project

    npm run build

Configuration

  1. Set up environment variables

    # Copy the example file
cp .env.example .env

# Edit .env with your credentials
nano .env

  2. Configure your OpenPages connection

    # Required
export OPENPAGES_BASE_URL="https://your-server.com/opgrc/api"

# Choose one authentication method:

# Option A: Basic Auth
export OPENPAGES_USERNAME="your-username"
export OPENPAGES_PASSWORD="your-password"

# Option B: Bearer Token
export OPENPAGES_BEARER_TOKEN="your-jwt-token"

Test Your Connection

Run the test script to verify everything is working:

node test-connection.js

You should see:

Testing OpenPages Connection...
✓ Success! Found X object types
✓ Success! Found X root folders
✓ Success! Found X tags
✓ Success! Query returned X results

All tests passed! ✓

Configure Claude Desktop

macOS

  1. Edit Claude Desktop config

    nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

  2. Add the MCP server

    {
  "mcpServers": {
    "openpages": {
      "command": "node",
      "args": ["/full/path/to/mcp-openpages-server/dist/index.js"],
      "env": {
        "OPENPAGES_BASE_URL": "https://your-server.com/opgrc/api",
        "OPENPAGES_USERNAME": "your-username",
        "OPENPAGES_PASSWORD": "your-password"
      }
    }
  }
}

  3. Restart Claude Desktop

Windows

  1. Edit Claude Desktop config

    notepad %APPDATA%\Claude\claude_desktop_config.json

  2. Add the MCP server (same JSON as macOS)

  3. Restart Claude Desktop

First Steps with Claude

Once configured, try these commands in Claude:

1. Explore Your Environment

Show me all the object types available in OpenPages

2. Search for Objects

Search for objects containing "audit" in OpenPages

3. Query Data

Query all business entities from OpenPages

4. Get Object Details

Get details for OpenPages object with ID 12345

5. Create an Object

Create a new SOXIssue in OpenPages named "Test Issue" with description "This is a test"

Common Commands

What you want to do Ask Claude
List object types "Show me all OpenPages object types"
Search objects "Search OpenPages for 'risk assessment'"
Get object details "Get OpenPages object 12345"
Create object "Create a new SOXRisk named 'Data Breach'"
Update object "Update OpenPages object 12345 description to 'Updated'"
Query objects "Query all open issues from OpenPages"
Check workflows "Show workflow status for object 12345"
List folders "Show me the folder structure in OpenPages"

Troubleshooting

Connection Failed

  • Verify OPENPAGES_BASE_URL is correct
  • Check network connectivity
  • Ensure credentials are valid

Authentication Error

  • Verify username/password or token
  • Check user is not locked
  • Ensure user has required permissions

Tool Not Found

  • Restart Claude Desktop
  • Check config file syntax
  • Verify file paths are absolute

Permission Denied

  • Check user permissions in OpenPages
  • Verify role assignments
  • Review security rules

Next Steps

  1. Read the full documentation

  2. Explore the API

    • Try different object types
    • Experiment with queries
    • Test workflow operations

  3. Customize for your needs

    • Add custom tools
    • Extend functionality
    • Integrate with other systems

Getting Help

Security Reminder

⚠️ Important: Never commit your .env file or credentials to version control!

What's Next?

Now that you're set up, explore the USAGE_GUIDE.md for:

  • Advanced query examples
  • Workflow automation
  • Bulk operations
  • Best practices
  • Integration patterns

Happy automating! 🚀