README.md•7.53 kB
# Chronos MCP Server 🔵
[](https://www.npmjs.com/package/chronos-mcp)
[](https://opensource.org/licenses/MIT)
Chronos is a Model Context Protocol (MCP) server tailored for the Stellar blockchain and designed specifically for integration with Claude Desktop and similar AI applications. Chronos empowers your AI assistant with on-chain tools enabling streamlined interactions with the Stellar network.
## Overview
Chronos MCP provides the following capabilities:
- **Connect to Stellar Wallets:** Securely connect to your wallet using a secret key.
- **List Wallet Tokens:** Retrieve and list all tokens held in a Stellar wallet.
- **Query Balances:** Get real-time balances for your XLM and other assets.
- **Transfer Funds:** Initiate transfers between Stellar wallets with ease.
Chronos is built to be extensible and operates as a standard Node.js package, allowing it to be easily deployed, installed, and integrated—similar to other MCP servers such as base-mcp.
## Features
- **Stellar Integration:** Fully interacts with the Stellar mainnet via the Horizon API.
- **Easy Deployment:** Publish and install Chronos using npm.
- **Claude Desktop Compatibility:** Seamlessly integrate with Claude Desktop by updating MCP server configuration.
- **Extensible Architecture:** Designed for future enhancements and new tool integrations.
## Prerequisites
- Node.js (v14 or higher)
- npm
- Stellar wallet credentials (secret key for connection)
- Internet connectivity to interact with the Stellar network
## Installation
### Option 1: Install from npm (Recommended)
Install Chronos globally:
```bash
npm install -g chronos-mcp
```
Or use it directly with npx:
```bash
npx chronos-mcp@latest
```
### Option 2: Install from Source
1. Clone the repository:
```bash
git clone https://github.com/yourusername/chronos-mcp.git
cd chronos-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
4. (Optional) Link globally for easier access:
```bash
npm link
```
### Option 3: Using Docker
You can also run Chronos MCP using Docker:
1. Build the Docker image:
```bash
docker build -t chronos-mcp .
```
2. Run the container:
```bash
docker run -it --rm chronos-mcp
```
For more detailed instructions on using Docker with Chronos MCP, including Docker Compose setup and integration with Claude Desktop, see the [Docker Usage Guide](docker-usage.md).
For information on testing your Docker setup locally, refer to the [Docker Usage Guide](docker-usage.md). This includes information about building the Docker image, running the container, and using Docker with Chronos MCP.
## Configuration
### Environment Variables
Chronos MCP uses environment variables for configuration, particularly for sensitive information like your Stellar secret key. The project uses `dotenv` to load environment variables from a `.env` file during development.
To configure environment variables:
1. Create a `.env` file in the project root:
```
STELLAR_SECRET_KEY=your_stellar_secret_key
STELLAR_NETWORK=mainnet
```
2. These variables will be automatically loaded when the application starts.
When using Docker, you can provide environment variables in several ways:
- Using the `--env-file` flag: `docker run -it --rm --env-file .env chronos-mcp`
- Using the `env_file` directive in docker-compose.yml
- Setting individual variables with the `-e` flag: `docker run -it --rm -e STELLAR_SECRET_KEY=your_key chronos-mcp`
### Claude Desktop Configuration
To use Chronos with Claude Desktop, update your Claude Desktop configuration file located at:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
Sample configuration for Claude Desktop:
```json
{
"mcpServers": {
"stellar": {
"command": "npx",
"args": ["chronos-mcp@latest"],
"env": {
"STELLAR_NETWORK": "mainnet",
"STELLAR_SECRET_KEY": "your_stellar_secret_key"
},
"disabled": false,
"autoApprove": []
}
}
}
```
For Docker integration with Claude Desktop, you can use:
```json
{
"mcpServers": {
"stellar": {
"command": "docker",
"args": ["run", "-i", "--rm", "--env-file", "/path/to/your/.env", "chronos-mcp"],
"env": {
"STELLAR_NETWORK": "mainnet"
},
"disabled": false,
"autoApprove": []
}
}
}
```
## Usage
Chronos MCP exposes the following tools via its MCP interface:
### connect_wallet
Connects to a Stellar wallet using the secret key.
**Example Command:**
> "Connect my wallet using secret key ______"
---
### list_tokens
Lists all tokens and assets in the specified Stellar wallet.
**Example Command:**
> "List my wallet tokens"
---
### get_balances
Retrieves the balance for XLM and any other assets.
**Example Command:**
> "What's my current XLM balance?"
---
### transfer_funds
Transfers funds from your wallet to another Stellar wallet.
**Parameters:**
- `secretKey`: Your wallet secret key.
- `destinationAddress`: The recipient's wallet address.
- `amount`: The amount to transfer.
- `asset` *(optional)*: Asset to transfer (defaults to XLM).
**Example Command:**
> "Transfer 0.5 XLM to [destination wallet address]"
## Testing
### Standard Testing
To test Chronos MCP locally:
```bash
npm test
```
This will run the project's test suite and verify that your server is working as expected.
### Docker Testing
To test the Docker setup locally, refer to the [Docker Usage Guide](docker-usage.md) for instructions. The guide covers:
- Building the Docker image
- Running the container with Docker Compose
- Integration with Claude Desktop
- Other Docker-related information
You can also use the included `test-client.js` script to test the Docker container:
```bash
node test-client.js
```
This script sends a simple MCP request to the Docker container and displays the response.
## Deployment
Chronos MCP is designed to function as a standard Node.js package and can be published to npm. Once published (e.g. via `npm publish`), Chronos can be installed globally or used via npx, just like any other MCP server.
For production deployment, consider wrapping Chronos in a system service (using systemd, launchd, etc.) for automatic restarts and monitoring.
## Extending Chronos
Chronos is built with extensibility in mind. To add new tools:
1. Create a new directory in the `src/tools` folder.
2. Implement your tool (include an `index.ts`, `schemas.ts`, and `handlers.ts`).
3. Export your tool in `src/tools/index.ts`.
4. Update the README with your tool's documentation and examples.
5. Write tests to ensure your new tool works correctly.
## License
This project is licensed under the [MIT License](LICENSE).
## Contributing
Contributions are welcome! Please consult the [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting issues, submitting pull requests, and other contribution instructions.
──────────────────────────────
This README is tailored specifically for Chronos MCP and outlines its deployment as a Node.js package, integration with Claude Desktop, and a comprehensive set of features to interact with the Stellar blockchain.