README.md•5.85 kB
# Trello MCP Server
A Model Context Protocol (MCP) server for interacting with the Trello API. This server enables AI assistants to retrieve information from Trello cards through a standardized interface.
## Features
- **Card Retrieval**: Get Trello cards by ID or direct link
- **Read-only Mode**: Optional read-only mode for safe operations
- **Type Safety**: Built with TypeScript and Zod for robust type validation
- **Debug Support**: Optional debug logging for troubleshooting
## Installation
### Prerequisites
- Node.js ≥ 22.7.0
- npm ≥ 10.8.2
- A Trello account with API access
### Setup
1. Clone the repository:
```bash
git clone https://github.com/LorhanSohaky/trello-mcp.git
cd trello-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Get your Trello API credentials:
- Visit [Trello Developer API Keys](https://trello.com/app-key)
- Copy your API Key
- Generate a Token by clicking the "Token" link
## Configuration
The server requires the following configuration parameters:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `apiKey` | string | Yes | - | Your Trello API Key |
| `apiToken` | string | Yes | - | Your Trello API Token |
| `debug` | boolean | No | false | Enable debug logging |
| `readOnly` | boolean | No | false | Enable read-only mode |
### Example Configuration
```json
{
"apiKey": "your_trello_api_key_here",
"apiToken": "your_trello_api_token_here",
"debug": false,
"readOnly": true
}
```
## Available Tools
### `getCardById`
Retrieves a Trello card by its unique ID.
**Parameters:**
- `idCard` (string): The ID of the Trello card to retrieve
**Example:**
```json
{
"tool": "getCardById",
"input": { "idCard": "5f1a2b3c4d5e6f7g8h9i0j1k" }
}
```
### `getCardByLink`
Retrieves a Trello card using its public link.
**Parameters:**
- `link` (string): The URL of the Trello card to retrieve
**Example:**
```json
{
"tool": "getCardByLink",
"input": { "link": "https://trello.com/c/abc123def/123-card-title" }
}
```
## Development
This project uses [Smithery](https://smithery.ai/) for MCP server development and deployment.
### Running in Development Mode
```bash
npm run dev
```
This will start the MCP server using Smithery's development tools with hot reloading.
### Linting and Formatting
The project uses [Biome](https://biomejs.dev/) for linting and formatting:
```bash
# Format and fix linting issues
npm run lint:fix
# Check for linting issues only
npm run lint
```
### Project Structure
```
├── .editorconfig # Editor configuration
├── .gitignore # Git ignore rules
├── biome.json # Biome linter/formatter config
├── lefthook.yaml # Git hooks configuration
├── LICENSE.md # MIT license
├── package.json # Node.js dependencies and scripts
├── smithery.yaml # Smithery MCP server configuration
├── README.md # This file
└── src/
├── index.ts # Main MCP server implementation
└── trello/
├── index.ts # Trello API client
├── cards.ts # Cards API implementation
└── schemas.ts # Zod schemas for type validation
```
## Usage with AI Assistants
This MCP server is designed to work with AI assistants that support the Model Context Protocol. Once configured, the assistant can use the provided tools to:
- Retrieve complete card information for project management tasks
- Get detailed card data when provided with Trello links
- Access all card properties including labels, members, due dates, and attachments
- Integrate Trello data into workflows and automation
## API Response Format
Both tools return the complete card object as JSON, containing all available card information including:
```json
{
"id": "card_id_here",
"name": "Card Title",
"desc": "Card Description",
"url": "https://trello.com/c/...",
"shortLink": "abc123",
"idBoard": "board_id",
"idList": "list_id",
"labels": [...],
"members": [...],
"due": "2025-01-01T00:00:00.000Z",
// ... and many other properties
}
```
## Tools and Technologies
- **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)**: Standardized protocol for AI-tool integration
- **[Smithery](https://smithery.ai/)**: MCP server development and deployment platform
- **[TypeScript](https://www.typescriptlang.org/)**: Type-safe JavaScript development
- **[Zod](https://zod.dev/)**: Runtime type validation and schema definition
- **[Biome](https://biomejs.dev/)**: Fast linter and formatter
- **[Lefthook](https://github.com/evilmartians/lefthook)**: Git hooks manager
## Error Handling
The server includes robust error handling for:
- Invalid card IDs
- Malformed Trello links
- API authentication failures
- Network connectivity issues
## Security
- The server supports read-only mode to prevent accidental modifications
- API credentials are required for all operations
- All inputs are validated using Zod schemas
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and add tests
4. Run linting: `npm run lint:fix`
5. Commit your changes: `git commit -am 'Add feature'`
6. Push to the branch: `git push origin feature-name`
7. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
## Support
For issues and questions:
- Open an issue on [GitHub Issues](https://github.com/LorhanSohaky/trello-mcp/issues)
- Check the [repository homepage](https://github.com/LorhanSohaky/trello-mcp) for updates
---
*This MCP server is built using the [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) and follows MCP best practices for tool integration.*