MCP 服务器

TrustLayer MCP Server

Provides read-only access to TrustLayer's public API, enabling users to query and retrieve data about parties, documents, projects, and other TrustLayer entities through MCP-compatible tools.

README

Unofficial TrustLayer MCP Server

Unofficial community Model Context Protocol (MCP) server for the Public TrustLayer API - read-only access.

Overview

This MCP server provides read-only access to the Public TrustLayer API data, allowing integration with:

API Documentation: This server implements the Public TrustLayer Platform API v1.0 and follows the public API documentation available at https://developers.trustlayer.io/.

Cursor IDE
n8n workflows
Claude Desktop
Other MCP-compatible tools

Features

Read-Only Access: Only GET operations are supported (no create, update, or delete)
Resources: List all TrustLayer entities (Parties, Documents, Projects, etc.)
Tools: Query specific entities by ID or list with filters
JSON Responses: All data returned as structured JSON
HTTP Transport: Deploy as HTTP server for remote access
Token Authentication: Support for per-request token via Authorization header

Prerequisites

Python 3.11+
TrustLayer API token

Installation

Navigate to the mcp-server directory:

cd mcp-server

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Create a .env file:

cp env.example .env

Edit .env and configure:

TRUSTLAYER_API_BASE_URL=https://api.trustlayer.io
TRUSTLAYER_API_VERSION=v1
# TRUSTLAYER_API_TOKEN is optional for HTTP mode (token from Authorization header)
# Required only for stdio mode
TRUSTLAYER_API_TOKEN=your_api_token_here

Configuration Options:

TRUSTLAYER_API_BASE_URL - Base URL for TrustLayer API (default: https://api.trustlayer.io)
TRUSTLAYER_API_VERSION - API version (default: v1)
TRUSTLAYER_API_TOKEN - API token (required for stdio mode, optional for HTTP mode)

Usage

Running the MCP Server

The MCP server can run in two modes:

1. Stdio Mode (for local MCP clients)

The MCP server runs via stdio and is typically started by MCP clients. To test manually:

Option 1: Using the wrapper script (recommended):

# Make sure the script is executable
chmod +x run_server.sh

# Run the server
./run_server.sh

Option 2: Direct Python execution:

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run the server
python -m src.server

2. HTTP Mode (for remote access)

To run the MCP server as an HTTP service:

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run the HTTP server
python run_http_server.py

The server will be available at http://localhost:8000 with the following endpoints:

http://localhost:8000/ - Health check and server info
http://localhost:8000/health - Health check endpoint
http://localhost:8000/mcp - MCP protocol endpoint

Note:

For HTTP mode: Token can be provided via Authorization header (recommended) or via TRUSTLAYER_API_TOKEN env var
For stdio mode: Token must be set in TRUSTLAYER_API_TOKEN env var

3. Docker Mode

To run the MCP server using Docker:

# Create .env file if it doesn't exist
cp env.example .env
# Edit .env and set TRUSTLAYER_API_TOKEN (optional for HTTP mode)

# Build and start the container
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

Rebuilding the Docker image:

If you've made changes to the code and need to rebuild the image:

# Stop and remove containers
docker-compose down

# Rebuild without cache (recommended after code changes)
docker-compose build --no-cache

# Start the container
docker-compose up -d

# Or do it all in one command
docker-compose down && docker-compose build --no-cache && docker-compose up -d

Quick rebuild and restart:

# Rebuild and restart in one command
docker-compose up -d --build

Checking if the server is running:

# Check container status
docker-compose ps

# Check health endpoint
curl http://localhost:8000/health

# View logs
docker-compose logs --tail=50

The server will be available at http://localhost:8000 with the same endpoints as HTTP mode.

Production Deployment

Systemd Service Setup

For production deployment on Linux servers, you can create a systemd service:

Create service file:

sudo nano /etc/systemd/system/trustlayer-mcp.service

Add the following content:

[Unit]
Description=TrustLayer MCP Server
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/mcp-server
Environment="PATH=/path/to/mcp-server/venv/bin"
EnvironmentFile=/path/to/mcp-server/.env
ExecStart=/path/to/mcp-server/venv/bin/python run_http_server.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Activate the service:

# Reload systemd
sudo systemctl daemon-reload

# Enable auto-start
sudo systemctl enable trustlayer-mcp

# Start the service
sudo systemctl start trustlayer-mcp

# Check status
sudo systemctl status trustlayer-mcp

# View logs
sudo journalctl -u trustlayer-mcp -f

Nginx Reverse Proxy

For production, it's recommended to use Nginx as a reverse proxy:

Create Nginx configuration:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        
        # For SSE/streaming
        proxy_buffering off;
        proxy_cache off;
    }
}

Enable SSL with Let's Encrypt:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Integration with Cursor

Option 1: Stdio Mode (Local)

Add to your Cursor settings (.cursor/mcp.json):

Option A: Using the wrapper script (recommended):

{
  "mcpServers": {
    "trustlayer": {
      "command": "/path/to/mcp-server/run_server.sh",
      "cwd": "/path/to/mcp-server",
      "env": {
        "TRUSTLAYER_API_TOKEN": "your_api_token_here",
        "TRUSTLAYER_API_BASE_URL": "https://api.trustlayer.io",
        "TRUSTLAYER_API_VERSION": "v1"
      }
    }
  }
}

Option B: Direct Python execution:

{
  "mcpServers": {
    "trustlayer": {
      "command": "/path/to/mcp-server/venv/bin/python3",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/mcp-server",
        "TRUSTLAYER_API_TOKEN": "your_api_token_here",
        "TRUSTLAYER_API_BASE_URL": "https://api.trustlayer.io",
        "TRUSTLAYER_API_VERSION": "v1"
      }
    }
  }
}

Example with absolute paths (using wrapper script):

{
  "mcpServers": {
    "trustlayer": {
      "command": "/path/to/mcp-server/run_server.sh",
      "cwd": "/path/to/mcp-server",
      "env": {
        "TRUSTLAYER_API_TOKEN": "your_api_token_here",
        "TRUSTLAYER_API_BASE_URL": "https://api.trustlayer.io",
        "TRUSTLAYER_API_VERSION": "v1"
      }
    }
  }
}

Important:

When using the wrapper script (run_server.sh): Just provide the full path to the script and set cwd
When using direct Python execution: Use the full path to your Python executable in the virtual environment and set PYTHONPATH
Always set cwd to the mcp-server directory

Option 2: HTTP Mode (Remote)

If you're running the HTTP server separately, connect via HTTP:

Basic connection (uses token from server config):

{
  "mcpServers": {
    "trustlayer": {
      "url": "http://localhost:8000/mcp",
      "transport": "streamable-http"
    }
  }
}

With Authorization header (recommended - token per client):

{
  "mcpServers": {
    "trustlayer": {
      "url": "http://localhost:8000/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your_api_token_here"
      }
    }
  }
}

For remote servers, replace localhost:8000 with your server's address.

Note: When using Authorization header, the token is passed with each request, allowing different clients to use different tokens. This is more secure than storing tokens in server configuration.

Integration with Claude Desktop

Add to Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Stdio Mode:

{
  "mcpServers": {
    "trustlayer": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-server",
      "env": {
        "TRUSTLAYER_API_TOKEN": "your_token_here",
        "TRUSTLAYER_API_BASE_URL": "https://api.trustlayer.io",
        "TRUSTLAYER_API_VERSION": "v1"
      }
    }
  }
}

HTTP Mode:

{
  "mcpServers": {
    "trustlayer": {
      "url": "http://your-server:8000/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your_api_token_here"
      }
    }
  }
}

Integration with n8n

Use the MCP server as a custom node or via HTTP interface. Start the HTTP server and connect to http://your-server:8000/mcp.

Configuration example:

{
  "url": "http://your-server:8000/mcp",
  "transport": "streamable-http",
  "headers": {
    "Authorization": "Bearer your_api_token_here"
  }
}

Note: Replace your-server:8000 with your actual server address and your_api_token_here with your TrustLayer API token.

Available Resources

The MCP server provides resources for:

trustlayer://parties/{id} - Individual parties
trustlayer://documents/{id} - Individual documents
trustlayer://projects/{id} - Individual projects
trustlayer://tags/{id} - Individual tags
trustlayer://compliance-profiles/{id} - Compliance profiles
trustlayer://party-types/{id} - Party types
trustlayer://custom-fields/{id} - Custom fields
trustlayer://reports/{id} - Reports
trustlayer://webhooks/{id} - Webhooks
trustlayer://branding/{id} - Branding configurations

Available Tools

Get Operations

get_party - Get a party by ID
get_document - Get a document by ID
get_project - Get a project by ID
get_contact - Get a contact by ID
get_party_contacts - Get all contacts for a party
get_party_compliance_profile - Get compliance profile for a party
get_party_compliance_certificate - Get compliance certificate for a party
get_party_document_request - Get document request for a party
get_compliance_profile - Get a compliance profile by ID
get_report - Get a report by ID

List Operations

list_parties - List all parties (with optional limit/offset)
list_documents - List all documents (with optional limit/offset)
list_projects - List all projects (with optional limit/offset)
list_tags - List all tags
list_compliance_profiles - List all compliance profiles
list_party_types - List all party types
list_custom_fields - List all custom fields
list_reports - List all reports
list_webhooks - List all webhooks

Project Structure

mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py              # Main MCP server (stdio mode)
│   ├── http_server.py         # HTTP MCP server
│   ├── trustlayer_client.py   # TrustLayer API client
│   ├── config.py              # Configuration
│   ├── resources.py           # MCP resources
│   └── tools.py                # MCP tools
├── run_server.sh              # Stdio server launcher script
├── run_http_server.py         # HTTP server launcher
├── test_server.py             # Test script to verify server setup
├── test_tools.py              # Test script to verify tools registration
├── pyproject.toml
├── requirements.txt
├── Dockerfile                  # Docker configuration
├── docker-compose.yml          # Docker Compose configuration
├── env.example                 # Environment variables example
└── README.md

Example Usage

In Cursor/Claude

You can ask questions like:

"List all parties in TrustLayer"
"Get details for party ID 12345"
"Show me all documents for party 12345"
"What compliance profile does party 12345 have?"

The MCP server will fetch the data from TrustLayer API and return it in a structured format.

Security

Read-Only: The MCP server only supports GET operations
Token Security: Store API tokens securely in environment variables or use Authorization headers
No Data Modification: No create, update, or delete operations are exposed
HTTPS Recommended: Use HTTPS in production environments
Firewall: Restrict access through firewall to only necessary IPs

Monitoring

Health Check

The server provides a health check endpoint:

curl http://localhost:8000/health

Expected response:

{"status": "healthy"}

Logs

Docker:

docker-compose logs -f

Systemd:

sudo journalctl -u trustlayer-mcp -f

Local: Logs are output to stdout/stderr when running directly.

Troubleshooting

Token Issues

Ensure TRUSTLAYER_API_TOKEN is set correctly in your environment or .env file. For HTTP mode, you can also provide the token via Authorization header.

Connection Issues

Verify TRUSTLAYER_API_BASE_URL is correct
Check network connectivity
Review server logs for error messages
For HTTP mode, ensure the server is running: curl http://localhost:8000/health

Port Already in Use

# Check what's using port 8000
sudo lsof -i :8000

# Or change the port in run_http_server.py

MCP Client Issues

Ensure Python is in your PATH
Verify the MCP server can be started manually
Check MCP client logs for connection errors
For stdio mode, verify paths in configuration are correct

Docker Issues

Ensure Docker and Docker Compose are installed
Check container logs: docker-compose logs
Verify .env file exists and is properly configured
Rebuild image if code changes: docker-compose build --no-cache

Development

Testing

Quick Verification Scripts

Test server setup and imports:

python test_server.py

This script verifies that:

Configuration loads correctly
Server can be imported
Tools are available

Test tools registration:

python test_tools.py

This script verifies that tools are properly registered and can be listed.

Test Stdio Server

Option 1: Using the wrapper script:

./run_server.sh