ltphat2204/teable-mcp-server

Teable MCP Server

A Model Context Protocol (MCP) server that connects Teable — the super-fast, open-source, no-code database — to LLMs like Claude, ChatGPT, and others.

This server enables AI agents to seamlessly query records, explore schema structures (spaces, bases, tables, views), and retrieve data from your Teable instance using natural language. It acts as a bridge, empowering your AI to interact with your data dynamically and intelligently.

🌟 What is Teable?

Teable is a next-generation, open-source, no-code database built on Postgres. It combines the ease of use of a spreadsheet with the power of a relational database.

• Hyper-fast: Handles millions of rows with ease.
• Open Source: You own your data. Self-hostable.
• SQL-like: Powerful querying capabilities.
• Real-time: Collaboration features built-in.
• API-first: Designed for developers and automation.

✨ Features

This MCP server exposes a comprehensive set of tools to LLMs, allowing for deep integration with your Teable database:

• query_teable: Query data from a specific table with advanced support for:
  • Filtering: Use SQL-like or JSON filter syntax to pinpoint exact data.
  • Sorting: Order functionality for organized results.
  • Limiting: Control record counts for efficient context usage.
  • Views: Filter records by specific database views.
• get_record: Retrieve precise details of a single record by its ID.
• get_record_history: Access the full change history of a specific record to track evolution over time.
• list_spaces: Discover all spaces available to the user.
• list_bases: detailed listing of all bases within a specific space.
• list_tables: detailed listing of all tables within a specific base.
• list_views: Retrieve all views within a table to understand different data perspectives.
• get_table_fields: Fetch the full schema (field definitions) of a table to enable the AI to understand your data structure and types.

🛠 Configuration

To use this server, you need a Teable API Key.

1. Get your API Key:

   • Log in to your Teable account and navigate to Personal Access Token settings.
   • Click Create New Token.
   • Enable all read permissions for the scopes (spaces, bases, tables, records, views, fields).
   • Select the appropriate bases you want the MCP server to access.
   • Save the token - you'll need this for configuration.

2. Environment Variables: You can configure the server using specific environment variables.

🚀 Usage

Note: For Option 1 and Option 2, since we are using the local source code, you must build the project first.

npm install && npm run build

Option 1: Using with Claude Desktop (Recommended)

Add the following configuration to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "teable": {
      "command": "node",
      "args": [
        "/absolute/path/to/teable-mcp-server/dist/index.js"
      ],
      "env": {
        "TEABLE_API_KEY": "mcp_sk_xxxxxxxxxxxxxx",
        "TEABLE_BASE_URL": "https://app.teable.ai/api"
      }
    }
  }
}

Note: Replace mcp_sk_xxxxxxxxxxxxxx with your actual API key.

Option 2: Using with Cursor

1. Open Cursor Settings.
2. Navigate to Features -> MCP.
3. Click + Add New MCP Server.
4. Enter a name (e.g., "Teable").
5. Select Type: command.
6. Command:

   node /absolute/path/to/teable-mcp-server/dist/index.js
   

7. Add your Environment Variables in the env section:
   • TEABLE_API_KEY: your_api_key
   • TEABLE_BASE_URL: https://app.teable.ai/api

💻 Local Development

1. Clone the repository:

   git clone https://github.com/ltphat2204/teable-mcp-server.git
   cd teable-mcp-server
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Debug using MCP Inspector:

   export TEABLE_API_KEY=your_api_key
   export TEABLE_BASE_URL=https://app.teable.ai/api
   npm run inspector
   

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License.