MCP Alchemy

🚀 MCP Alchemy Project Documentation

MCP Alchemy is a tool designed to enhance the interaction between Claude Desktop and databases. It enables Claude to directly access and manipulate various databases, and retrieve relevant data information.

🚀 Quick Start

Get started with MCP Alchemy by following these steps to set up the project environment.

📦 Installation

1. Clone the Repository

git clone git@github.com:runekaagaard/mcp-alchemy.git
cd mcp-alchemy
uv sync

2. Install Dependencies

Install the database driver as needed:

uv pip install psycopg2-binary

3. Configure Claude Desktop

Add the following content to claude_desktop_config.json:

"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-alchemy", "-m", "mcp_alchemy.server", "main"],

✨ Features

Tools

• all_table_names

  • Retrieve the names of all tables in the database.
  • Input: None
  • Output: A comma-separated list of table names.

  users, orders, products, categories
  

• filter_table_names

  • Find tables based on a substring.
  • Input: q (string)
  • Output: Matching table names.

  Input: "user"
  Output: "users, user_roles, user_permissions"
  

• schema_definitions

  • Obtain detailed schema information for specified tables.
  • Input: table_names (array of strings)
  • Output: Table definitions including column names, types, primary keys, foreign key relationships, and nullable flags.

  users:
      id: INTEGER, primary key, autoincrement
      email: VARCHAR(255), nullable
      created_at: DATETIME
      
      Relationships:
        id -> orders.user_id
  

• execute_query

  • Execute SQL queries and output results in a vertical format.
  • Input: query (string), optional params (object)
  • Output: Well-formatted vertical results, supporting intelligent truncation of large result sets and access to data outside the full context window.

  1. Row
  id: 123
  name: John Doe
  created_at: 2024-03-15T14:30:00
  email: NULL
  
  Result: 1 row
  

Environment Variables

• DB_URL: SQLAlchemy database URL (required).
• CLAUDE_LOCAL_FILES_PATH: Directory path for full result sets (optional).
• EXECUTE_QUERY_MAX_CHARS: Maximum output length (optional, default 4000).

📚 Documentation

API Interfaces

MCP Alchemy provides a series of API interfaces for developers to call database functions. The main interfaces include:

• List all table names (all_table_names)
• Filter table names (filter_table_names)
• Get table schema information (schema_definitions)
• Execute queries (execute_query)

Integration with Claude Local Files

When claude-local-files is configured, MCP Alchemy can:

• Access large result sets outside the context window.
• Generate detailed reports and visualizations.
• Perform in-depth data analysis.
• Export results for further processing.

Development Guide

1. Clone the repository: git clone git@github.com:runekaagaard/mcp-alchemy.git
2. Install dependencies: Run uv sync and the necessary database driver installation commands.
3. Configure Claude Desktop: Refer to the above configuration example to integrate MCP Alchemy into Claude.

Contribution Guide

Community contributions are welcome! Whether it's reporting issues, proposing new features, improving documentation, or contributing code, we're eager to hear from you:

• Submit issues or feature requests.
• Submit Pull Requests to fix bugs or add new features.
• Enhance documentation or share usage cases.
• Discuss and exchange experiences on GitHub.

📄 License

This project is licensed under the Mozilla Public License Version 2.0.

Other LLM Projects by the Author

• MCP Redmine: Manage Redmine projects and tasks with Claude Desktop.
• MCP Notmuch Sendmail: Integrate the Notmuch mail system with Claude Desktop.
• MCP Alchemy: A database interaction tool for Claude Desktop.

We hope this documentation helps you better understand and use the MCP Alchemy project!