Sample MCP Server

What is Sample MCP Server?

Sample MCP Server is a Model Context Protocol (MCP) server that connects to a PostgreSQL database. Built with Go and GORM, it provides CRUD operations and aggregation for financial accounts, categories, and transactions. It is intended as a reference implementation for MCP server development.

How to use Sample MCP Server?

Prerequisites: Go 1.24+, Mage, Docker, and Docker Compose. Clone the repository, then start the PostgreSQL database with mage docker:up and build with mage build. For development, run mage dev. Configuration is done via a config.yml file or the MCP_SERVER_CONFIG environment variable.

Key features of Sample MCP Server

• Account management (create, read, update, delete)
• Category management (create, read, update, delete)
• Transaction tracking (create, read, update, delete)
• Transaction aggregation (sum, count by account)
• Configurable PostgreSQL connection (also supports MySQL and MSSQL)

Use cases of Sample MCP Server

• Manage financial accounts with create, read, update, delete operations.
• Organize transactions into categories for better tracking.
• Record and retrieve financial transactions with amounts, dates, and descriptions.
• Aggregate transaction data to compute sums and counts per account.

FAQ from Sample MCP Server

What runtime dependencies are required?

Go 1.24 or higher, the Mage build tool, Docker and Docker Compose, and a PostgreSQL instance (or the included Docker setup).

How do I configure the database connection?

Copy config.yml.sample to config.yml and edit the values. You can also point to a custom config file using the MCP_SERVER_CONFIG environment variable. Default settings are provided for host, port, user, password, and database name.

Which database systems are supported?

PostgreSQL is the default, but the configuration also supports MySQL and MSSQL via the Type field.

How can I run tests?

Unit tests: mage test. Integration tests: mage integrationtest, which automatically starts Docker services and waits for PostgreSQL.

What does the data model look like?

The model includes three entities: Account (ID, name, type), Category (ID, name, type), and Transaction (amount, date, description, with relationships to accounts and categories).