Portosync MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with financial portfolio data from multiple sources. This server enables AI assistants like Claude to interact with your financial portfolio balances through standardized MCP tools, with initial support for KSEI (Indonesian central custodian holding data across all securities).

Features

• 🏦 KSEI Integration - Fetch portfolio data from KSEI AKSES using goksei library
• 🚀 Dual Mode Support - Run via stdio (MCP standard) or HTTP server
• 🐳 Docker Ready - Multi-stage Alpine-based container
• 🔒 Secure - Runs as non-root user with minimal dependencies

Upcoming features

• 📊 Portfolio Tracking - Store and query financial balances as time series data
• 🔄 Background Jobs - Periodic data fetching with jitter for reliability
• 🗄️ SQLite Database - Lightweight, self-contained database storage

Tools Available

get_portfolio

Retrieve portfolio balances from KSEI accounts.

Parameters:

• account_names (array of strings, optional): List of account names to retrieve balances from. If empty or not provided, returns balances from all configured accounts.

Installation

Prerequisites

• KSEI AKSES account credentials
• Go 1.25+ (if building from source)

Option 1: Docker (Recommended)

# Pull the image
docker pull ghcr.io/chickenzord/portosync:latest

# Run in stdio mode (for MCP clients)
docker run --rm -i \
  -e KSEI_ACCOUNTS="email1:pass1,email2:pass2" \
  -e KSEI_AUTH_CACHE_DIR="/tmp/ksei_cache" \
  ghcr.io/chickenzord/portosync:latest mcp-stdio

# Run in HTTP mode  
docker run --rm -p 8080:8080 \
  -e KSEI_ACCOUNTS="account1:user1:pass1,account2:user2:pass2" \
  -e KSEI_AUTH_CACHE_DIR="/tmp/ksei_cache" \
  -e BIND_ADDR=":8080" \
  ghcr.io/chickenzord/portosync:latest mcp-http

Option 2: Go Install

go install github.com/chickenzord/portosync/cmd/portosync@latest

Option 3: Build from Source

git clone https://github.com/chickenzord/portosync.git
cd portosync
go build -o portosync ./cmd/portosync

Configuration

Environment Variables

• KSEI_ACCOUNTS (required): KSEI account configurations in format "email1:password1,email2:password2"
• KSEI_AUTH_CACHE_DIR (optional): Directory to cache KSEI authentication tokens (default: temp directory)
• KSEI_PLAIN_PASSWORD (optional): Set to "false" to use encrypted passwords (default: true)
• BIND_ADDR (optional): HTTP server bind address (default: ":8080")

KSEI Account Configuration

The KSEI_ACCOUNTS environment variable should contain comma-separated account configurations:

KSEI_ACCOUNTS="your.email@example.com:yourpassword,business.email@example.com:businesspassword"

Each account configuration follows the format: username:password

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "portosync": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "KSEI_ACCOUNTS=your.email@example.com:yourpassword",
        "-e", "KSEI_AUTH_CACHE_DIR=/tmp/ksei_cache",
        "ghcr.io/chickenzord/portosync:latest",
        "mcp-stdio"
      ]
    }
  }
}

Or if using a local binary:

{
  "mcpServers": {
    "portosync": {
      "command": "portosync",
      "args": ["mcp-stdio"],
      "env": {
        "KSEI_ACCOUNTS": "your.email@example.com:yourpassword",
        "KSEI_AUTH_CACHE_DIR": "/tmp/ksei_cache"
      }
    }
  }
}

VS Code with MCP Extension

{
  "mcp.servers": [
    {
      "name": "portosync",
      "command": "portosync",
      "args": ["mcp-stdio"],
      "env": {
        "KSEI_ACCOUNTS": "your.email@example.com:yourpassword",
        "KSEI_AUTH_CACHE_DIR": "/tmp/ksei_cache"
      }
    }
  ]
}

Usage Examples

Once configured with an MCP client, you can use natural language commands:

• "Show me my current portfolio balances"
• "What's the history of my BBCA holdings in KSEI?"
• "Show balances for my personal account only"
• "What stocks do I own and their current values?"

Development

Running Locally

# Set environment variables
export KSEI_ACCOUNTS="your.email@example.com:yourpassword"
export KSEI_AUTH_CACHE_DIR="/tmp/ksei_cache"

# Run in stdio mode
go run ./cmd/portosync mcp-stdio

# Run in HTTP mode  
go run ./cmd/portosync mcp-http

Testing

# Run tests
go test ./...

# Test with a real KSEI account
go run ./cmd/portosync mcp-stdio < test-requests.json

Building

# Build binary
go build -o portosync ./cmd/portosync

# Build Docker image
docker build -t portosync .

Docker Compose Example

version: '3.8'
services:
  portosync:
    image: ghcr.io/chickenzord/portosync:latest
    environment:
      - KSEI_ACCOUNTS=personal:your.email@example.com:yourpassword
      - KSEI_AUTH_CACHE_DIR=/app/cache
      - BIND_ADDR=:8080
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - ./cache:/app/cache
    command: ["mcp-http"]

API Reference

The HTTP mode exposes MCP endpoints at:

• POST /mcp/v1/initialize - Initialize MCP session
• POST /mcp/v1/tools/list - List available tools
• POST /mcp/v1/tools/call - Call a tool

See the MCP specification for detailed API documentation.

Troubleshooting

Common Issues

Authentication Error: Verify your KSEI credentials in KSEI_ACCOUNTS are correct and the account is active.

Connection Error: Ensure KSEI AKSES is accessible and your network allows connections to their servers.

Cache Issues: Clear the KSEI_AUTH_CACHE_DIR directory if experiencing persistent authentication problems.

Logs

Container logs:

docker logs <container-id>

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• goksei - Go library for KSEI AKSES integration
• MCP Specification - Model Context Protocol specification
• Claude Desktop - AI assistant with MCP support

Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📖 Documentation: Wiki

---

Built with ❤️ in Indonesia for better financial literacy and MCP ecosystem