Larks

Python implementation of the Larks MCP server using FastMCP, converted from Node.js/TypeScript.

Installation

cd python
pip install -r requirements.txt

Running the Server

Option 1: Using Docker Compose (Recommended)

# Copy .env.example to .env and fill in your credentials
cp .env.example .env
# Edit .env with your credentials

# Build and start the container
docker compose up -d

# View logs
docker compose logs -f

# Stop the container
docker compose down

Option 2: Using .env file (Local)

# Copy .env.example to .env and fill in your credentials
cp .env.example .env
# Edit .env with your credentials

# Run the server
python server.py

Option 3: Using environment variables

# Set environment variables
export LARKS_CLIENT_ID=your_client_id
export LARKS_CLIENT_SECRET=your_client_secret
export MCP_PORT=48080

# Run the server
python server.py

Note: Environment variables take precedence over .env file values.

Configuration

The server loads configuration from .env file and environment variables (env vars take precedence):

• LARKS_CLIENT_ID: OAuth app ID (required)
• LARKS_CLIENT_SECRET: OAuth app secret (required)
• LARKS_REDIRECT_URI: OAuth redirect URI (default: http://localhost:48080/oauth/callback)
• LARKS_BEARER_TOKEN: Direct bearer token (optional, fallback if OAuth not used)
• LARKS_DOMAIN: OAuth domain (default: https://open.larksuite.com)
• LARKS_API_DOMAIN: API domain (default: https://open.larksuite.com)
• MCP_PORT: Server port (default: 48080)
• MCP_HOST: Server host (default: 0.0.0.0)

Cursor MCP Configuration

Use streamable HTTP transport:

{
  "mcpServers": {
    "larks-docs": {
      "transport": "streamableHttp",
      "url": "http://localhost:48080/mcp"
    }
  }
}

Start the server separately:

python server.py

Docker

Building the Image

docker build -t larks-mcp-python .

Running with Docker Compose

# Start the service
docker compose up -d

# View logs
docker compose logs -f larks-mcp-python

# Stop the service
docker compose down

Environment Variables in Docker

You can provide environment variables in several ways:

1. Via docker-compose.yml (recommended for Docker):

   environment:
     - LARKS_CLIENT_ID=your_client_id
     - LARKS_CLIENT_SECRET=your_client_secret
   

2. Via .env file (mounted as volume):

   volumes:
     - ./.env:/app/.env:ro
   

3. Via host environment variables:

   export LARKS_CLIENT_ID=your_client_id
   export LARKS_CLIENT_SECRET=your_client_secret
   docker compose up -d
   

Features

• ✅ Streamable HTTP transport (plain HTTP POST, no SSE)
• ✅ OAuth authentication flow
• ✅ Document content fetching
• ✅ Same API as Node.js version
• ✅ Environment variable and .env file configuration
• ✅ Automatic token refresh handling
• ✅ Docker support with docker-compose

Differences from Node.js Version

• Uses FastMCP for easier server setup
• Async/await pattern throughout
• Python-native HTTP client (httpx)
• Same functionality, cleaner Python code
• Uses python-dotenv for .env file support