BI
Finance

Bitable MCP Server for Lark Tables

Access Lark Bitable tables via the MCP server to interact with and manage tables using predefined tools through the Model Context Protocol.

View on GitHub
Quick Install
npx -y @lloydzhou/bitable-mcp

Overview

Bitable MCP Server for Lark Tables exposes Lark (Feishu) Bitable spreadsheets as tools that language models can call through the Model Context Protocol (MCP). Instead of giving a model direct API keys or raw table exports, this server translates MCP tool calls into safe, predictable operations on your Bitable: reading rows, querying columns, updating records, and adding new entries.

This pattern is useful when you want an LLM to interact with structured financial data (budgets, transactions, forecasts) without leaking credentials or requiring model-side plumbing. The server centralizes authentication, enforces access patterns, and exposes a small set of tool primitives that an LLM can use to inspect and change tables.

Features

  • Exposes Lark Bitable as MCP-compatible tools (list, query, read, create, update, delete)
  • Centralized authentication for Lark (app id/secret, tokens) and optional API key for MCP clients
  • Simple JSON RPC-style execute endpoint for model tool calls
  • Support for table schema inspection and basic query filters
  • Dockerfile and npm-based launch for local or containerized deployment
  • Logging and basic error responses suitable for integration with LLM toolchains

Installation / Configuration

Prerequisites:

  • Node.js (>=16) and npm, or Docker
  • A Lark / Feishu app with access to Bitable (app_id, app_secret, and appropriate scopes)
  • The Bitable App ID / Base ID(s) you want to expose

Quick start (local):

git clone https://github.com/lloydzhou/bitable-mcp.git
cd bitable-mcp
npm install

Create a .env file in the project root with the required keys. Example .env:

# Lark / Feishu credentials
LARK_APP_ID=cli_xxxxxxx
LARK_APP_SECRET=xxxxxxxxxxxx
LARK_TENANT_KEY=tn_xxxxxxx

# The Bitable base or app IDs you will expose
BITABLE_BASE_ID=app_xxxxxxx

# Server settings
PORT=3000
MCP_API_KEY=your-mcp-api-key-here   # optional: require this header from clients

Start the server:

npm start
# or for development
npm run dev

Docker build & run:

docker build -t bitable-mcp .
docker run -e LARK_APP_ID=... -e LARK_APP_SECRET=... -e BITABLE_BASE_ID=... -p 3000:3000 bitable-mcp

Configuration notes:

  • Use environment variables to keep secrets out of source control.
  • If you enable an MCP API key, clients must send it as Authorization: Bearer <MCP_API_KEY> or the configured header.

Available Resources

The server exposes a small, well-documented set of MCP tools that map to common table operations. Typical resources include:

  • list_tables: enumerates available Bitable tables and their IDs
  • get_schema: returns column definitions for a table (types, names)
  • query_rows: fetches rows matching simple filter criteria (e.g., column equals value, date ranges)
  • get_row: fetches a single row by row ID
  • create_row: inserts a new row given column values
  • update_row: updates specific columns in an existing row
  • delete_row: removes a row by ID
  • attachments: (optional) upload or fetch file metadata attached to rows

These tools are exposed as MCP tool metadata (name, description, parameters) and an execute endpoint that accepts tool invocations and returns structured JSON results.

Example tool metadata request (tool discovery):

curl -H "Authorization: Bearer <MCP_API_KEY>" \
  http://localhost:3000/mcp/tools

Example tool invocation (create a row):

curl -X POST http://localhost:3000/mcp/execute \
  -H "Authorization: Bearer <MCP_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "create_row",
    "params": {
      "table_id": "tbl_abc123",
      "values": {
        "Date": "2026-04-01",
        "Category": "Travel",
        "Amount": 125.50,
        "Note": "Taxi from airport"
      }
    }
  }'

Responses follow a consistent JSON structure with status, data, and error fields to make parsing from models and orchestration layers straightforward.

Use Cases

  • Finance assistant: Let an LLM answer questions such as “What was our total travel spend last quarter?” by calling query_rows to aggregate the Amount column and returning a computed summary.
  • Transaction ingestion: A chat interface or model pipeline can convert a natural-language expense description into a structured row via create_row, enforcing schema constraints server-side.
  • Audit & approval workflow: The model can list newly added rows awaiting review (query_rows with a Status=Pending filter), propose edits, and then call update_row to mark items approved.
  • Reconciliation: Use get_schema and query_rows to compare bank-exported lines against Bitable rows, flagging mismatches the LLM can present to a human reviewer.

Security & Best Practices

  • Keep Lark/Feishu credentials in a secrets manager; never commit .env to Git.
  • Restrict MCP access with an API key or a short-lived signed token to prevent unauthorized tool usage.
  • Limit exposed tables and columns to only what the model needs—avoid exposing sensitive PII unless strictly controlled.
  • Log tool calls for auditability but redact sensitive cell values in logs.

Troubleshooting

  • Authentication errors: verify LARK_APP_ID and LARK_APP_SECRET and that your app has permission for Bitable scopes.
  • Permission denied on table access: confirm the Bitable base and table IDs and that your app is granted access to those tables.
  • Rate limits: Lark APIs have rate limits—if you see throttling, implement retries/backoff in your MCP client or batching in the server.

For implementation details, examples, and issue reporting, see the repository

Tags:finance