Perseus MCP Server

MCP (Model Context Protocol) server for integrating Plaid financial data with Perseus.

Installation

Install the Perseus MCP server via NPM:

npx --yes @onbreeze/perseus-mcp@latest

Configuration

MCP Client Setup (Cursor/Claude Desktop)

Add the following configuration to your MCP client settings:

{
  "mcpServers": {
    "perseus": {
      "command": "npx",
      "args": ["--yes", "@onbreeze/perseus-mcp@latest"],
      "env": {
        "PERSEUS_API_URL": "https://your-perseus-deployment.com/api",
        "PERSEUS_API_KEY": "your-api-key-from-perseus-dashboard"
      }
    }
  }
}

Environment Variables

The MCP server requires two environment variables:

• PERSEUS_API_URL: The URL of your Perseus web API endpoint (e.g., https://perseus.example.com/api)
• PERSEUS_API_KEY: Your personal API key from the Perseus dashboard

Available Tools

The Perseus MCP server provides three tools for interacting with Plaid financial data:

1. connect_bank

Initiates the Plaid Link flow to connect a new bank account.

Input Parameters:

• redirectHint (optional): Hint about where to redirect after linking

Example:

{
  "tool": "connect_bank",
  "arguments": {
    "redirectHint": "dashboard"
  }
}

2. get_balances

Retrieves account balances from connected bank accounts.

Input Parameters:

• itemId (optional): Specific item ID to get balances for
• accountIds (optional): Array of specific account IDs to get balances for

Example:

{
  "tool": "get_balances",
  "arguments": {
    "itemId": "item_123abc"
  }
}

3. get_transactions

Fetches transactions from connected bank accounts.

Input Parameters:

• mode (optional): Either "snapshot" (default) or "date_range"
• startDate (optional): Start date for date_range mode (YYYY-MM-DD format)
• endDate (optional): End date for date_range mode (YYYY-MM-DD format)

Example:

{
  "tool": "get_transactions",
  "arguments": {
    "mode": "date_range",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }
}

Getting Started

1. Set up Perseus Web: Deploy the Perseus web application and obtain your API key from the dashboard
2. Configure MCP Client: Add the Perseus MCP server to your MCP client configuration
3. Connect Bank Account: Use the connect_bank tool to link your first bank account
4. Access Financial Data: Use get_balances and get_transactions to retrieve your financial information

Development

To run the MCP server locally for development:

# Clone the repository
git clone https://github.com/mikeOnBreeze/obz-perseus.git
cd obz-perseus/perseus-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

License

MIT

Support

For issues and questions, please visit: https://github.com/mikeOnBreeze/obz-perseus/issues